takt 0.50.0 → 0.51.0

package/README.md

@@ -257,6 +257,8 @@ Exec presets resolve in this order: project `.takt/exec/presets/` → global `$T
 
 When `/go` runs, TAKT generates `.takt/exec/workflow.yaml` and executes it through the normal workflow engine. Inline text after `/go` is treated as an additional note. `/go` without prior conversation or inline task text does not generate the workflow. Use `/cancel` to exit without running.
 
+Exec input supports image attachments while editing the current line. Use `/paste-image` or `Ctrl+V` to attach a clipboard image on macOS, or paste an OSC 1337 inline image from a compatible terminal. TAKT inserts a `[Image #N]` placeholder. Reference that placeholder in an Assistant message or `/go` note to send the image with that Assistant request; placeholders that were not attached in the session are treated as normal text. When `/go` runs, referenced stored images are copied into the generated task spec and listed in its attachment section. Supported image types are PNG, JPEG, GIF, and WebP. Inline and clipboard images are limited to 10 MiB. TAKT rejects unsupported image data, mismatched inline-image filename types, oversized images, and stored attachments whose temp path is missing, a symlink, or not a regular file. Providers without native image input receive the attachment as a local path reference in the prompt.
+
 Normal agent steps, parallel sub-steps, and loop detection judges may set `session_key` to share or isolate persona sessions. System steps, workflow_call steps, and parallel parent steps cannot set `session_key`. TAKT builds the runtime key as `session_key` plus the resolved provider, so values must be non-empty strings that do not collide with other generated session routes.
 
 ## Configuration
@@ -269,6 +271,33 @@ model: sonnet       # passed directly to provider
 language: en        # en or ja
 ```
 
+To let TAKT choose provider/model per step, set `provider: auto` and define `auto_routing` candidates:
+
+```yaml
+provider: auto
+auto_routing:
+  strategy: balanced   # cost, balanced, or performance
+  router:
+    provider: claude-sdk
+    model: claude-haiku-4-5-20251001
+  candidates:
+    - name: coding
+      description: Implementation, tests, debugging, and refactoring
+      provider: codex
+      model: gpt-5
+      cost_tier: medium
+    - name: lightweight
+      description: Formatting and small mechanical edits
+      provider: claude-sdk
+      model: claude-haiku-4-5-20251001
+      cost_tier: low
+  rules:
+    tags:
+      implementation: coding
+```
+
+Auto-routing decisions are written locally to `.takt/events/` as NDJSON. TAKT does not upload routing decisions. Local recording is enabled by default, can be configured with `telemetry.routing_decisions`, and can be inspected or changed with `takt telemetry status|enable|disable`.
+
 Or use API keys directly (no CLI installation required for Claude, Codex, OpenCode):
 
 ```bash

package/builtins/en/facets/instructions/findings-manager.md

@@ -14,4 +14,4 @@ Compare reviewer raw findings with the previous ledger and return the reconcilia
 
 ## Dispute adjudication (dispute/waiver)
 
-Adjudicate findings the coder claims are valid but unfixable. Approve only when the prior step response contains an explicit claim with the finding ID, a reason, and file:line evidence, the evidence is plausible against the ledger, and the severity is not critical. Record approvals in waivedFindings with the reason and evidence. If the claim is unconvincing, keep the finding open and record it in disputeNotes. When in doubt, keep it open. Never invent waivers for findings without a claim.
+Adjudicate findings the coder claims are stale (already addressed, or citing structures that no longer exist in the current code) or valid but unfixable. Approve only when the prior step response contains an explicit claim with the finding ID, a reason, and file:line evidence, the evidence is plausible against the ledger, and the severity is not critical. For staleness claims, verify the file:line evidence against the current code. Record approvals in waivedFindings with the reason and evidence. If the claim is unconvincing, keep the finding open and record it in disputeNotes. When in doubt, keep it open. Never invent waivers for findings without a claim.

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

@@ -4,6 +4,10 @@ When no ledger is available, use reports in the Report Directory and fix the iss
 **Fix principles:**
 - When a finding includes a "suggested fix", follow it rather than inventing your own workaround
 - Fix the target code directly. Do not deflect findings by adding tests or documentation instead
+- When a ledger is available: dispute a finding only when it contradicts the current code, or is structurally unresolvable within this step's responsibility. Do not pretend to fix it; state a formal dispute under `## Disputed Findings` with concrete counter-evidence and file:line references (follow the format in the Finding Contract instructions). A dispute is pending adjudication — it does not mean resolved or waived
+  - Do not cite transient tool failures, task difficulty, or uncertainty as grounds for a dispute
+  - Only cite a "deliberate trade-off" when you have evidence of an existing spec or a user decision
+- When no ledger is available, the dispute mechanism does not exist, so do not use it. For findings you cannot fix, do not claim you fixed them; note them as blockers in the work results
 
 **Report reference policy:**
 - When a parseable Finding Contract ledger summary / `findings-ledger.json` is available, use the consolidated ledger as the single authoritative source for deciding what to fix.
@@ -14,14 +18,16 @@ When no ledger is available, use reports in the Report Directory and fix the iss
 - 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 open findings in this iteration (`new` / `persists` / `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)
+- When a ledger is available: every open finding in this iteration (`new` / `persists` / `reopened`) has been either fixed or disputed under `## Disputed Findings` with evidence. These are the only two valid outcomes; leave no finding in neither state
+- When no ledger is available: every finding you could fix has been fixed, and findings you could not fix are noted as blockers in the work results rather than claimed as fixed
+- For findings you fixed, potential occurrences of the same `family_tag` have been fixed simultaneously (no partial fixes that cause recurrence)
+- For findings you fixed where the code defect can be verified by an automated test at the appropriate layer, at least one regression test per `family_tag` has been added (mandatory for config-contract and boundary-check findings). When a meaningful automated test cannot be created, state the reason and the verification steps taken (commands run and results) in the work results. Do not satisfy this criterion with a meta-test such as asserting a file exists. Do not write tests for findings you disputed
 - 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)**
+If you disputed any findings, include `## Disputed Findings` (follow the format in the Finding Contract instructions).
 ## Work results
 - {Summary of actions taken}
 ## Changes made

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

@@ -12,4 +12,10 @@ whether this loop is healthy (converging) or unproductive (diverging or oscillat
 - When the ledger exists but is incomplete, follow the ledger for mapped findings and treat unmapped raw findings as potential new entries awaiting findings-manager reconciliation.
 - When the ledger is absent, unreadable, or unparseable, use the latest review reports in the Report Directory as primary evidence.
 - Are fixes actually being applied to the code?
+  - If fixes have landed but the same findings keep coming back (the findings
+    no longer match the current code), the deadlock is in the findings, not
+    the code. A dispute route remains (dispute → manager adjudication →
+    waive), so judge this as breakable by replanning and route back to plan.
 - Is the number of new / reopened findings decreasing overall?
+
+Choose ABORT only when neither fixing, replanning, nor disputing can break the deadlock.

package/builtins/en/facets/knowledge/architecture.md

@@ -106,6 +106,17 @@ Prohibited patterns:
 - Error handling centralized (no try-catch scattered everywhere)
 - Business logic not leaking into Controller/View
 
+**Exception Translation at Protocol Boundaries:**
+
+Adapters such as HTTP, CLI, GraphQL, and message consumers are boundaries that translate internal exceptions into external protocol representations. Scattering the same try-catch / response translation across endpoints or handlers easily makes status codes, error shapes, logs, and authorization failures inconsistent. Centralize exception translation in a dedicated layer at the adapter boundary, and keep only truly cross-cutting translations in a global handler.
+
+| Criteria | Judgment |
+|----------|----------|
+| Each endpoint / handler implements the same translation from the same exception to the same protocol representation | REJECT |
+| Translation to protocol representation lives in the application or domain layer | REJECT |
+| API-specific exception translation is placed in a global handler shared by all APIs | REJECT |
+| Translation to external representation is centralized in an exception translation layer at the adapter boundary | OK |
+
 ## Resolve at the Boundary
 
 Values such as config, options, providers, permissions, and paths should be resolved at the boundary before entering the core flow. Main processing should assume values are already resolved and should not keep asking config sources.

package/builtins/en/facets/knowledge/backend.md

@@ -62,6 +62,7 @@ data class Order(
 | Controller directly referencing Repository | REJECT. Must go through UseCase layer |
 | Outward dependencies from domain layer (DB, HTTP, etc.) | REJECT |
 | Direct dependencies between adapters (inbound → outbound) | REJECT |
+| Types or identifiers in the application/domain layer carry protocol-specific meaning such as HTTP request/response, endpoint, or status code | REJECT. Translate them into use-case concepts at the boundary. A domain term that happens to contain words such as Request is not itself a violation |
 
 ## API Layer Design (Controller)
 
@@ -208,6 +209,37 @@ fun confirm(confirmedBy: String): OrderConfirmedEvent {
 | Structural validation (@NotBlank, etc.) in domain | REJECT. Belongs in API layer |
 | UseCase-level validation inside Aggregate | REJECT. Read Model queries belong in UseCase layer |
 
+### Entry Validation Ownership
+
+Give each entry constraint a single owner and a single enforcement mechanism. Validations with different purposes per layer are not duplication, but do not re-implement the same boundary and the same condition in multiple mechanisms. Where declarative validation is active, invalid input is rejected before the handler; the downstream check remains reachable for valid input but redundantly re-evaluates the same condition and cannot define the violation response. Whether declarative validation is actually active depends on the framework configuration — verify it, then make a single mechanism the effective owner.
+
+```kotlin
+// NG - same constraint twice; declarative validation owns the violation response
+@GetMapping("/orders/{id}")
+fun get(@PathVariable @Size(max = MAX_ID) id: String): OrderResponse {
+    requireIdWithinLimit(id)  // runs only for valid input and cannot define the violation response
+    return orderReadService.get(id).toResponse()
+}
+
+// OK - unify on the declaration and delete the procedural check
+@GetMapping("/orders/{id}")
+fun get(@PathVariable @Size(max = MAX_ID) id: String): OrderResponse =
+    orderReadService.get(id).toResponse()
+```
+
+In the Spring example, constraints on scalar arguments such as `@PathVariable` or `@RequestParam` work only when method validation is active. Older setups commonly require class-level `@Validated`; Spring 6.1+ can use built-in method validation depending on configuration.
+
+On a validation violation, the response may fall through to the framework's default translation outside your own exception hierarchy (some setups translate to 400, others leave it untranslated as 500). Judge not by whether a default translation is used, but by whether the status and response shape match the explicit API contract. The exception type thrown on violation depends on configuration and version, so do not guess; pin the actual exception and response with an integration test. Follow "Exception Translation Scope" for where the translation belongs.
+
+| Criteria | Judgment |
+|----------|----------|
+| Same entry and same condition implemented in multiple validation mechanisms | REJECT. Make a single mechanism the effective owner and delete the unreachable side |
+| Status and response shape on a validation violation do not match the explicit API contract (including implicit reliance on the default translation with no contract defined) | REJECT. Make the contract explicit and wire the translation |
+| No test pinning the status and response shape on validation violation | REJECT. Verify the actual exception type with an integration test |
+| Validation policy is inconsistent across entrypoints sharing the same trust boundary and input contract | REJECT. State the reason for the difference or unify the policy |
+| External error contract depends on messages from the runtime's default locale | REJECT. Use stable error codes or explicit messages as the contract |
+| Constraint values (max length, etc.) share a single constant across validation and API spec | OK |
+
 ### Read and Write Entrypoints
 
 Separate read and write entrypoints. Read-side query boundaries have no side effects; writes are handled by commands or UseCases.
@@ -259,6 +291,7 @@ class OrderExceptionHandler {
 | Throwing generic Exception or RuntimeException | REJECT. Use specific exception types |
 | Empty try-catch blocks | REJECT |
 | Controller swallowing exceptions and returning 200 | REJECT |
+| Expressing an actually reachable call pattern (e.g., a caller with a different role) as a 500 | REJECT. Make it an explicit 4xx; guarantee "unreachable" assumptions with authorization |
 
 ### Exception Translation Scope
 
@@ -270,6 +303,7 @@ Translate exceptions into HTTP status codes at an exception translation layer on
 | API-specific exception mapping is added to a global handler | Scope is too broad. Keep it inside the target API boundary |
 | Authentication failures, input validation, and common error shapes shared by all APIs | OK. Handle at a global boundary |
 | HTTP representation mapping lives in the application or domain layer | REJECT. Keep it at the HTTP adapter boundary |
+| Multiple translation layers handle the same exception type without a contract for scope and precedence | REJECT. Consolidate under a single owner or make the non-overlapping applicability explicit |
 
 ## Domain Model Design
 
@@ -384,6 +418,18 @@ data class OrderEntity(
 | Business logic in Entity | REJECT. Entity is data structure only |
 | Repository implementation in domain layer | REJECT. Belongs in adapter/outbound |
 
+### Persistence Boundary for Structured Attributes
+
+For structured attributes in relational or read-model persistence, choose the storage format based on update granularity, integrity, size, and schema evolution — not just current query requirements. Do not implicitly use a domain type's generic serialized form as the persistence contract; use a persistence-specific representation or an explicit mapping. Event-store type identifiers and payloads may use an explicit, versioned serialization contract; govern their evolution with the CQRS-ES compatibility and upcaster rules.
+
+| Criteria | Judgment |
+|----------|----------|
+| Bounded structure read and written as a whole, with no need for search, joins, referential integrity, or partial updates | Consider a structured column (JSON, etc.) |
+| Referential integrity, an independent lifecycle, or joins with other tables matter | Normalize into its own table |
+| The DB's structured-column features (jsonb, etc.) can guarantee the needed search, indexing, and partial updates, and integrity requirements are met | A structured column is also a valid choice |
+| Domain type is converted directly by a generic serializer, implicitly using its field names as the DB schema | REJECT. Insert a persistence-specific representation or an explicit mapping |
+| Field changes to stored structures have no chosen path among compatible reads, migration, or rebuild, and no test pinning it | REJECT. Choose one path and pin it with a test |
+
 ## Authentication & Authorization Placement
 
 Authentication and authorization are cross-cutting concerns handled at the appropriate layer.
@@ -414,6 +460,34 @@ fun execute(input: DeleteInput, currentUserId: String) {
 | Authorization logic in UseCase or domain layer | REJECT. Belongs in Controller layer |
 | Data access control in Controller | REJECT. Belongs in UseCase layer |
 | Authentication processing inside Controller | REJECT. Belongs in Filter/Interceptor |
+| Application-layer service reads the security context directly (e.g., resolving the current user) | REJECT. Resolve at the boundary and pass as an argument |
+| The same authorization check is duplicated in the Controller and a lower layer | REJECT. Consolidate the responsibility in one place |
+
+## Distinguishing the Caller from the Domain Actor
+
+Treat the API caller (authenticated principal) and the business actor recorded on the data (person in charge, author, confirmer) as separate concepts. They diverge on ingestion, delegated operations, and administrative paths.
+
+| Criteria | Judgment |
+|----------|----------|
+| Unconditionally recording the caller as the business actor | Warning. Verify it does not break on ingestion, delegated, or administrative paths |
+| Reusing the creation-time caller, via state, as the actor of later operations | REJECT. Pass the performer as an argument per operation |
+| Requiring an actor field before the business actor is actually determined | Warning. Check whether it can be recorded at the operation that determines it (approval, confirmation, etc.) |
+| Resolving denormalized display names (etc.) at the boundary of the operation that establishes the fact | OK |
+| Placing resolution logic that assumes the caller is a member of the resource on a path also used by non-members | REJECT |
+
+The author of a memo is "whoever performed that operation"; the confirmer is "whoever performed the confirmation". Obtain the actor from each operation's performer. Facts determined later, such as the person in charge, are recorded at the operation/event that determines them — do not force a value at creation time.
+
+```kotlin
+// NG - Store the creation-time caller in state and reuse it as the actor of later operations
+fun addMemo(text: String): MemoAddedEvent {
+    return MemoAddedEvent(id, text, authorId = this.registeredBy)  // registrant != memo author
+}
+
+// OK - Receive the performer per operation
+fun addMemo(text: String, authorId: String): MemoAddedEvent {
+    return MemoAddedEvent(id, text, authorId = authorId)
+}
+```
 
 ## Test Strategy
 

package/builtins/en/facets/knowledge/cqrs-es.md

@@ -52,6 +52,7 @@ The Command Model (Aggregate) role is to "receive commands, make decisions, and
 | Holding fields not used for decisions | REJECT |
 | Branching state transitions with origin metadata such as `source` / `input` / `origin` / `channel` / `type` | REJECT by default |
 | Rejecting, only for a specific input source, a state allowed by the existing Aggregate's normal lifecycle | REJECT |
+| Keeping the creation-time caller in Aggregate state and reusing it as the actor of later events | REJECT. Pass the performer with each command |
 
 Being used in an `if` / `require` branch is not enough to justify keeping a field in Aggregate state. First verify that the branch or validation is an essential invariant of the whole Aggregate.
 
@@ -266,6 +267,40 @@ OrderPlaced, PaymentReceived, ItemShipped
 OrderUpdated, OrderDeleted
 ```
 
+### Fact Events vs Request Events
+
+Events express facts that occurred, and their names come from business meaning. A `...Requested` suffix or the current number of consumers does not by itself distinguish a fact event from a command in disguise. Accepting or starting a request can be a business fact; a message whose only meaning is instructing a known destination to execute work is a command.
+
+| Decision axis | Fact event | Consider a command |
+|---------------|------------|--------------------|
+| Business meaning | An occurrence such as acceptance, start, or rejection that matters to audit or replay | Its only purpose is to make a specific process run |
+| Emitter lifecycle | Used by later decisions such as waiting, duplicate rejection, or timeout | The emitter tracks neither state nor outcome |
+| Outcome | Continues to another uncertain fact such as completion or failure | Can run immediately within the same boundary and return its result there |
+| Consumers | Consumers may change without changing event meaning | Destination and operation are the message's meaning |
+
+Split events by independent business facts, not by technical consumers. Do not emit duplicate state and trigger events for the same occurrence; EventHandlers and projections subscribe to the fact owned by the emitting Aggregate. Multiple events are appropriate only when independently named, audited, and replayed facts occur together. Do not pack another Aggregate's internal state or initialization details into the event; resolve stable IDs or references at the boundary.
+
+```kotlin
+// NG - One business fact duplicated as separate state and technical trigger events
+fun addItem(itemId: String, productId: String, quantity: Int): List<OrderEvent> = listOf(
+    OrderItemLinkedEvent(orderId, itemId),                 // for state
+    OrderItemCreationRequestedEvent(orderId, itemId, productId, quantity), // for triggering (a command in effect)
+)
+
+// OK - A single event carrying the content that is factual for the emitting Aggregate
+fun addItem(itemId: String, productId: String, quantity: Int): OrderItemAddedEvent =
+    OrderItemAddedEvent(orderId, itemId, productId, quantity)
+```
+
+| Criteria | Judgment |
+|----------|----------|
+| Classifying a message as an event or command from its suffix or current consumer count alone | REJECT. Judge business meaning and lifecycle |
+| Splitting the same business fact into a state event (Linked, etc.) and a trigger event (Requested, etc.) | REJECT. Merge them into the fact owned by the emitting Aggregate |
+| An asynchronous request to an external service or another context where acceptance or waiting is a business fact and completion/failure is tracked | OK. It can be expressed as the fact that the request was accepted |
+| Adding a dedicated request event for processing that an existing fact event (confirmed, approved, etc.) can drive | REJECT. Have an EventHandler, and a domain policy when needed, subscribe to the existing fact |
+| Recording an occurrence that only changes another Aggregate's state as an event in one's own stream | REJECT. Facts belong to the stream of the Aggregate where they happened |
+| Routing an operation unrelated to an Aggregate's own state or lifecycle through it and relaying it to the target Aggregate | REJECT. Send the command to the target Aggregate and perform membership or existence checks at the boundary that owns the invariant |
+
 ### Event Type Hierarchy with sealed interface
 
 Aggregate events should use a sealed interface type hierarchy. The Aggregate root ID should be required as a common field, enabling exhaustive `when` checks.
@@ -370,6 +405,20 @@ CQRS+ES migration must distinguish DB schema migration, data migration, event up
 | Handler changes multiple Aggregates | REJECT |
 | Command has no validation | REJECT |
 | Handler executes queries to make decisions | Needs review |
+| The return contract does not match the number of events an operation can produce | Needs review. Choose a single, optional, collection, or result type from domain cardinality and language/framework conventions |
+
+### Contract Lifetimes of Commands and Events
+
+Events are long-lived contracts persisted as history, so stored type identifiers and payloads must remain replayable. Whether the type identifier is a fully qualified class name or a logical name, and whether changes use an upcaster, alias, or migration, depends on the event store and serialization strategy.
+
+Commands are usually short-lived messages created and handled at the application boundary, but some architectures persist them for scheduling, outbox delivery, retries, dead-letter handling, or audit. Decide placement and compatibility from responsibility and the actual storage contract, not from an assumption that every command is transient. Domain models should not depend on transport- or framework-specific command types; translate them into domain arguments and value objects at the application or adapter boundary.
+
+| Criteria | Judgment |
+|----------|----------|
+| A domain model directly receives a transport- or framework-specific command type | REJECT. Translate it into domain input at the application or adapter boundary |
+| An application message unused by domain classes sits in the domain package | Move it to the application boundary |
+| A command package is moved or renamed without checking for persisted references | REJECT. Check scheduling, outbox, retry, dead-letter, and audit storage contracts |
+| A stored event type identifier or payload changes without a conversion path | REJECT. Provide compatibility for the identifier and serialization strategy in use. Direct change is allowed only when no persisted events exist yet; release status is not the criterion |
 
 Good command handler:
 ```

package/builtins/en/facets/knowledge/frontend.md

@@ -90,6 +90,8 @@ Accessible names, roles, and states are UI contracts consumed by assistive techn
 | A new interactive element has no accessible name | REJECT |
 | Checked, expanded, disabled, or similar state is not exposed to assistive technologies | Warning |
 | An existing accessible name is changed without being required by the task | REJECT |
+| A dynamic accessible name is assembled by concatenating fragments without checking the final sentence for meaning and naturalness | REJECT |
+| Distinct elements in the same interaction context cannot be identified by name or programmatic context (row/group association, etc.) | REJECT. Including the target name in the accessible name is a strong way to identify it |
 | Existing accessible names are preserved while missing role/state is added | OK |
 | The reason and impact scope for changing an existing contract are explicit | OK |
 
@@ -139,6 +141,7 @@ State should hold canonical values such as user input, server data, and temporar
 | Multiple state fields have invariants that require constant synchronization | REJECT |
 | Display labels, counts, totals, all-selected flags, sorted results, or grouped results are kept as canonical state | REJECT |
 | API sending, persistence, or diffing depends on derived state instead of canonical state | REJECT |
+| A display-position sequence number after filtering, paging, or grouping is treated as the ordering of the source data | REJECT. Define which collection's order the label represents and derive it from that collection |
 | Only canonical state is stored, and display, aggregation, and decisions are derived via selectors, render logic, or useMemo | OK |
 | Derived values required by external contracts are generated from canonical state at send or persistence boundaries | OK |
 
@@ -255,6 +258,7 @@ Fetch data from screen-specific API endpoints. Do not assemble screens by repurp
 | Reusing list API response for detail screen | REJECT |
 | Display unit and API fetch unit mismatch | REJECT |
 | Fetching all records just for a decision (should use aggregation API) | REJECT |
+| A concept the UI needs is missing from the response, and a semantically different body/description field is implicitly repurposed as a heading | REJECT. Define the summary/fallback as an explicit display contract, or add a dedicated field |
 | Each screen has dedicated fetch endpoints returning only needed data | OK |
 
 ```tsx
@@ -284,7 +288,7 @@ Communication is scoped to the active tab/screen. Do not prefetch for other tabs
 
 ## Shared Components and Abstraction
 
-Common UI patterns should be shared components. Copy-paste of inline styles is prohibited.
+Common UI patterns should be shared components. Copy-paste of inline styles is prohibited. UI that represents the same role or semantic state (placeholder, disabled, unconfirmed, etc.) must align copy, styling, and screen-reader output within the same shared component or an explicit design contract; presentation may vary with display context (hierarchy, density, theme), but the meaning and interaction contract must hold.
 
 ```tsx
 // ❌ WRONG - Copy-pasted inline styles

package/builtins/en/facets/knowledge/security.md

@@ -232,6 +232,7 @@ Prevent data access across tenant boundaries. Authorization (who can operate) an
 | Write operations use client-provided tenant ID | REJECT |
 | Endpoint using tenant resolver has no authorization control | REJECT |
 | Some paths in role-based branching don't account for tenant resolution | REJECT |
+| Authentication mechanism coverage does not extend to the endpoint's expected caller (role, token type) | REJECT |
 
 ### Read-Write Consistency
 
@@ -277,6 +278,8 @@ fun getSettings(): SettingsResponse {
 
 For endpoints with role-based branching, verify that tenant resolution succeeds on all paths.
 
+Watch for the reverse pattern as well. When adding an endpoint dedicated to a specific role, extend the coverage of the mechanism that authenticates that role (filters, etc.) and add role-required authorization in the same change. Outside the authentication mechanism's coverage the expected caller is never authenticated in the first place, and without authorization, unexpected roles get through.
+
 ## OWASP Top 10 Checklist
 
 | Category | Check Items |

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

@@ -22,11 +22,11 @@ You are the implementer. Focus on implementation, not design decisions.
 - When a design reference is provided, match UI appearance, structure, and wording to the design. Do not add, omit, or change anything on your own judgment
 - Work only within the specified project directory (reading external files for reference is allowed)
 
-**Feedback from review is absolute. Your understanding is wrong.**
+**Do not dismiss review feedback from memory or guesswork.**
 - If reviewer says "not fixed", first open the file and verify the facts
 - Drop the assumption "I should have fixed it"
-- Fix all flagged issues with Edit tool
-- Don't argue; just comply
+- Fix every finding that is valid and resolvable with the operations allowed in this step, using the Edit tool
+- Do not mechanically repeat a failed fix without re-verifying the current code
 
 **Be aware of AI's bad habits:**
 - Hiding uncertainty with fallbacks → Prohibited

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

@@ -232,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

@@ -122,6 +122,7 @@ 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
 
@@ -282,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

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
 
@@ -233,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/workflows/backend-cqrs-for-local-llm.yaml

@@ -145,7 +145,7 @@ steps:
       - condition: Implementation is complete
         next: reviewers
       - condition: Cannot proceed with implementation (environment issue or missing information)
-        next: ABORT
+        next: plan
 
   - name: reviewers
     tags:

package/builtins/en/workflows/backend-for-local-llm.yaml

@@ -142,7 +142,7 @@ steps:
       - condition: Implementation is complete
         next: reviewers
       - condition: Cannot proceed with implementation (environment issue or missing information)
-        next: ABORT
+        next: plan
 
   - name: reviewers
     tags:

package/builtins/en/workflows/draft.yaml

@@ -49,7 +49,6 @@ steps:
     policy:
       - coding
       - testing
-    session: refresh
     knowledge:
       $param: impl_knowledge
     provider_options:

package/builtins/en/workflows/dual-for-local-llm.yaml

@@ -148,7 +148,7 @@ steps:
       - condition: Implementation is complete
         next: reviewers
       - condition: Cannot proceed with implementation (environment issue or missing information)
-        next: ABORT
+        next: plan
 
   - name: reviewers
     tags:

package/builtins/en/workflows/dual.yaml

@@ -124,7 +124,6 @@ steps:
       - testing
       - design-fidelity
       - screen-api
-    session: refresh
     knowledge:
       - frontend
       - react

package/builtins/en/workflows/frontend-for-local-llm.yaml

@@ -145,7 +145,7 @@ steps:
       - condition: Implementation is complete
         next: reviewers
       - condition: Cannot proceed with implementation (environment issue or missing information)
-        next: ABORT
+        next: plan
 
   - name: reviewers
     tags:

package/builtins/en/workflows/takt-default-for-local-llm.yaml

@@ -141,7 +141,7 @@ steps:
       - condition: Implementation is complete
         next: reviewers
       - condition: Cannot proceed with implementation (environment issue or missing information)
-        next: ABORT
+        next: plan
 
   - name: reviewers
     tags:

package/builtins/en/workflows/takt-default-refresh-all.yaml

@@ -118,7 +118,6 @@ steps:
     policy:
       - coding
       - testing
-    session: refresh
     knowledge:
       - takt
       - architecture

package/builtins/en/workflows/takt-default-refresh-fast.yaml

@@ -117,7 +117,6 @@ steps:
     policy:
       - coding
       - testing
-    session: refresh
     knowledge:
       - takt
       - architecture

package/builtins/ja/facets/instructions/findings-manager.md

@@ -14,4 +14,4 @@
 
 ## 異議の裁定（dispute/waiver）
 
-coder が「正当だが修正不能」と申告した指摘を裁定してください。承認の条件は、直前ステップ応答に finding ID・理由・file:line 証跡を伴う明示的な申告があり、証跡が台帳と照らして妥当で、severity が critical でないことのすべてです。承認は waivedFindings に理由と証跡付きで記録してください。説得力がなければ open のまま disputeNotes に記録してください。迷ったら open を維持してください。申告のない finding への waive の発明は禁止です。
+coder が「現状コードと乖離している（修正済み・実在しない構造への指摘）」または「正当だが修正不能」と申告した指摘を裁定してください。乖離の申告は、証跡の file:line を現状コードと照らして確認してください。承認の条件は、直前ステップ応答に finding ID・理由・file:line 証跡を伴う明示的な申告があり、証跡が台帳と照らして妥当で、severity が critical でないことのすべてです。承認は waivedFindings に理由と証跡付きで記録してください。説得力がなければ open のまま disputeNotes に記録してください。迷ったら open を維持してください。申告のない finding への waive の発明は禁止です。