takt 0.41.0 → 0.43.0

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

@@ -212,6 +212,7 @@ Detect comments that simply restate code behavior in natural language.
 | REJECT | JSDoc that only paraphrases the function name without adding information |
 | OK | Explains why a particular implementation was chosen |
 | OK | Explains the reason behind seemingly unusual behavior |
+| OK | Explains the calculation basis or components of a constant or magic number |
 | Best | No comment needed — the code itself communicates intent |
 
 ```typescript
@@ -238,6 +239,10 @@ if (status === 'interrupted') {
 // OK - Reason behind seemingly odd behavior
 // stay can cause loops, but is only used when explicitly specified by the user
 return step.name;
+
+// OK - Calculation basis for a constant
+// paddingTop + paddingBottom + button height
+const footerHeight = 24 + 12 + 48;
 ```
 
 **Direct State Mutation Detection Criteria:**
@@ -374,14 +379,14 @@ Don't overlook compromises made to "just make it work."
 | Swallowed errors | Empty `catch {}`, `rescue nil` |
 | Magic numbers | Unexplained `if (status == 3)` |
 
-## Strict TODO Comment Prohibition
+## Unfinished Code Detection
 
-"We'll do it later" never gets done. What's not done now is never done.
+Unfinished-code judgment follows the coding policy. In architecture review, check whether TODO/FIXME comments, empty implementations, or stubs are being used as substitutes for required boundaries, authorization, validation, or contract updates.
 
-TODO comments are immediate REJECT.
+TODO/FIXME without an issue number, external blocker, and removal condition is REJECT.
 
 ```kotlin
-// REJECT - Future-looking TODO
+// REJECT - Authorization check deferred with TODO
 // TODO: Add authorization check by facility ID
 fun deleteCustomHoliday(@PathVariable id: String) {
     deleteCustomHolidayInputPort.execute(input)
@@ -398,12 +403,12 @@ fun deleteCustomHoliday(@PathVariable id: String) {
 }
 ```
 
-Only acceptable TODO cases:
+Acceptable TODO/FIXME cases:
 
 | Condition | Example | Judgment |
 |-----------|---------|----------|
-| External dependency prevents implementation + Issued | `// TODO(#123): Implement after API key obtained` | Acceptable |
-| Technical constraint prevents + Issued | `// TODO(#456): Waiting for library bug fix` | Acceptable |
+| External dependency prevents implementation + issue exists + removal condition documented | `// TODO(#123): Implement after API key obtained` | Acceptable |
+| Technical constraint prevents implementation + issue exists + removal condition documented | `// TODO(#456): Waiting for library bug fix` | Acceptable |
 | "Future implementation", "add later" | `// TODO: Add validation` | REJECT |
 | "No time for now" | `// TODO: Refactor` | REJECT |
 
@@ -429,7 +434,7 @@ When NOT to apply DRY:
 
 ## Spec Compliance Verification
 
-Verify that changes comply with the project's documented specifications.
+Contract-change consistency follows the coding policy. In architecture review, check whether changes contradict documented specifications, types, schemas, or config formats.
 
 Verification targets:
 
@@ -460,10 +465,10 @@ REJECT when these patterns are found:
 
 ## Call Chain Verification
 
-When new parameters/fields are added, verify not just the changed file but also callers.
+Missing wiring after contract changes follows the coding policy. In architecture review, check whether new parameters or fields actually reach callers, producers, and readers instead of staying local to the changed file.
 
 Verification steps:
-1. When finding new optional parameters or interface fields, `Grep` all callers
+1. When finding new optional parameters or interface fields, search all callers
 2. Check if all callers pass the new parameter
 3. If fallback value (`?? default`) exists, verify if fallback is used as intended
 
@@ -471,7 +476,7 @@ Danger patterns:
 
 | Pattern | Problem | Detection |
 |---------|---------|-----------|
-| `options.xxx ?? fallback` where all callers omit `xxx` | Feature implemented but always falls back | grep callers |
+| `options.xxx ?? fallback` where all callers omit `xxx` | Feature implemented but always falls back | Check callers |
 | Tests set values directly with mocks | Don't go through actual call chain | Check test construction |
 | `executeXxx()` doesn't receive `options` it uses internally | No route to pass value from above | Check function signature |
 
@@ -493,12 +498,12 @@ Call chain verification applies not only to "missing wiring" but also to the rev
 
 | Pattern | Problem | Detection |
 |---------|---------|-----------|
-| TTY check when all callers require TTY | Unreachable branch remains | grep all callers' preconditions |
+| TTY check when all callers require TTY | Unreachable branch remains | Check all callers' preconditions |
 | Null guard when callers already check null | Redundant defense | Trace caller constraints |
 | Runtime type check when TypeScript types constrain | Not trusting type safety | Check TypeScript type constraints |
 
 Verification steps:
-1. When finding defensive branches (TTY check, null guard, etc.), grep all callers
+1. When finding defensive branches (TTY check, null guard, etc.), check all callers
 2. If all callers already guarantee the condition, guard is unnecessary → REJECT
 3. If some callers don't guarantee it, keep the guard
 

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

@@ -84,6 +84,54 @@ Event Granularity:
 - Appropriate: `ShippingAddressChanged` → Intent is clear
 - Too coarse: `OrderModified` → What changed is unclear
 
+## Event Evolution
+
+Events are persisted contracts. When the current event type changes, old events must still be replayable. Translation of old events belongs in the upcaster / migration layer at the event-store boundary, not in the event type itself or in domain logic.
+
+| Criteria | Judgment |
+|----------|----------|
+| Persisted event type or fields changed with no translation path | REJECT |
+| Current event type keeps aliases or compatibility-only properties for old field names | REJECT. Keep history compatibility in upcasters |
+| Aggregate or apply directly interprets old event shapes | REJECT. Convert to current events before replay |
+| Event carries "previous value" only for compatibility | REJECT. Events represent the fact after it happened |
+| Upcaster converts old payloads to the current event meaning | OK |
+| Tests verify old payloads deserialize into current events through the upcaster | OK |
+
+Responsibility split for event evolution:
+
+| Responsibility | Place |
+|----------------|-------|
+| Current event meaning and fields | Event type |
+| Translation of old payloads | Upcaster / migration layer |
+| State restoration by event replay | Aggregate `apply` |
+| Guarantee that old events can become current events | Upcaster tests |
+
+```kotlin
+// NG - mixing old-field compatibility into the current event type
+data class OrderAssignedEvent(
+    val orderId: String,
+    @JsonAlias("assigneeId")
+    val assigneeIds: List<String>
+)
+
+// OK - current event type represents only the current contract
+data class OrderAssignedEvent(
+    val orderId: String,
+    val assigneeIds: List<String>
+)
+```
+
+```kotlin
+// OK - convert old payloads to current payloads in the upcaster
+when (eventType) {
+    OrderAssignedEvent::class.java.typeName -> {
+        event.moveTextFieldToArray("assigneeId", "assigneeIds")
+    }
+}
+```
+
+Whether to keep old event classes depends on the framework and operations policy. In general, do not treat old classes as normal domain events; treat old serialized type names and payloads as the upcaster input contract and cover them with tests.
+
 ## Command Handlers
 
 | Criteria | Judgment |

package/builtins/en/facets/knowledge/existing-system.md

@@ -0,0 +1,70 @@
+# Existing System Knowledge
+
+## Existing System Contracts
+
+In an existing system, contracts are not limited to explicit APIs. Values and structures observed by users or developers also function as contracts. A small code change can affect production screens, tests, reviews, and maintenance workflows.
+
+| Criteria | Judgment |
+|----------|----------|
+| User-visible copy or state changes | Contract change |
+| A value asserted by tests changes | Contract change |
+| Hook or component call shape changes | Contract change |
+| Only file placement or type names change | May still be a maintenance contract change |
+| Closed internal duplication is removed | Internal change if impact is contained |
+
+## Diff Classification
+
+Changes in existing systems are classified by causal relationship to the request. The question is whether the request requires the change, not whether the change is in a touched file.
+
+| Classification | Decision criteria |
+|----------------|-------------------|
+| Required change | Directly required to satisfy the request |
+| Related change | Required to wire, verify, or keep a required change consistent |
+| Unnecessary change | The request still succeeds without it |
+| Dangerous unnecessary change | The request still succeeds without it and it changes an existing contract |
+
+### Boundary of Related Changes
+
+A related change must have an explainable connection to a required change. Proximity, same file, or same responsibility is not enough.
+
+| Example | Classification |
+|---------|----------------|
+| Updating callers after adding a required parameter | Related change |
+| Deleting an old store after changing persistence boundary | Related change |
+| Renaming a touched component's Props type by preference | Unnecessary change |
+| Changing a hook return shape to a props object as cleanup | Dangerous unnecessary change |
+
+## Conflicts With General Quality Criteria
+
+In maintenance work, general design improvements and framework style are not always the highest priority. Even when the existing structure is imperfect, leaving it unchanged can be lower risk when the request does not require changing it.
+
+| Situation | Judgment |
+|-----------|----------|
+| Component extraction would look cleaner but is unnecessary for this fix | Do not change |
+| Renaming or relocating Props types only to match common style | Do not change |
+| The existing structure cannot satisfy the request | Change the minimum necessary scope |
+| The existing structure is the cause of the bug | Change it with reason and impact scope documented |
+
+## Meaning of Comments and Tests
+
+Comments and tests may preserve historical constraints or intent. Even comments that look explanatory can act like contracts when they document calculation rationale, platform constraints, or known workaround reasons.
+
+| Target | Handling |
+|--------|----------|
+| Calculation rationale comments | Preserve |
+| Constraint or workaround comments | Preserve |
+| Comments contradicting code | Correct |
+| Comments that only restate function names | May consider deleting |
+| Existing test expectations | Treat as existing contracts |
+
+## Maintenance Change Risk
+
+For maintenance work, preserving existing behavior is more important than making new code look better. Even a technically good change increases review cost and regression risk when it is outside the request.
+
+| Change | Risk |
+|--------|------|
+| Rename | Increases grep, history tracing, and review scope |
+| File move | Changes ownership boundaries, imports, and history tracing |
+| UI contract change | Changes user experience, assistive technology behavior, and tests |
+| Test weakening | Reduces regression detection |
+| Extra abstraction | Adds present understanding cost for future flexibility |

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

@@ -81,6 +81,18 @@ Third-party UI libraries such as data grids, date pickers, charts, and virtualiz
 | The real component is rendered with representative props and verified not to crash at screen level | OK |
 | Prop shapes are chosen by referencing existing in-project usage patterns and the installed version | OK |
 
+### Accessibility Contracts
+
+Accessible names, roles, and states are UI contracts consumed by assistive technologies and tests. Add appropriate accessibility attributes for new UI elements, but treat changes to existing accessibility contracts like other user-facing copy or behavior changes.
+
+| Criteria | Judgment |
+|----------|----------|
+| 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 |
+| 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 |
+
 ## State Management
 
 Child components do not modify their own state. They bubble events to parent, and parent manipulates state.
@@ -117,6 +129,19 @@ Exception (OK for child to have local state):
 | Inappropriate useEffect dependencies | REJECT |
 | Initial load tied to unstable Context/Provider function references | REJECT |
 
+### Canonical and Derived State
+
+State should hold canonical values such as user input, server data, and temporary UI state. Display values, aggregates, selection states, sorted results, and grouped results that can be computed from canonical state are derived values and must not be kept as independent state.
+
+| Criteria | Judgment |
+|----------|----------|
+| A value that can always be computed from one state is kept as another state | REJECT |
+| 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 |
+| 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 |
+
 State Placement Guidelines:
 
 | State Nature | Recommended Placement |

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

@@ -120,6 +120,41 @@ When shared state is required, call the hook once in the nearest common parent a
 | Multiple components call the same stateful hook independently when they need shared state | REJECT |
 | A hook returns JSX | REJECT |
 
+### Props Type Placement and Hook Boundaries
+
+Props types that belong to a single component should generally live in the same file as that component. Separate type files are appropriate when the contract is shared by multiple components, is part of a public API, or has independent meaning as a domain model.
+
+| Criteria | Judgment |
+|----------|----------|
+| A single component's private Props type is moved to a `types` file without a clear reason | Warning |
+| Props are moved to a separate file only so a hook can import a component's Props type | REJECT |
+| Shared Props/data contracts used by multiple components or public APIs live in a separate file | OK |
+| A hook returns state, events, and derived values while a container maps them to component props | OK |
+| Even when a hook returns a props-like object, the hook does not depend on the component's Props type | OK |
+
+```tsx
+// REJECT - the hook depends on a specific component's Props contract
+import type { DialogProps } from './Dialog'
+
+export function useDialog(): { dialogProps: DialogProps } {
+  return { dialogProps: { open, onOpenChange } }
+}
+
+// OK - component-local Props stay with the component
+interface DialogProps {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+}
+
+export function Dialog(props: DialogProps) {
+  return <Modal {...props} />
+}
+
+// OK - the hook returns UI state and operations, and the caller passes them to the component
+const dialog = useDialog()
+return <Dialog open={dialog.open} onOpenChange={dialog.setOpen} />
+```
+
 ## Handling exhaustive-deps
 
 `react-hooks/exhaustive-deps` is not a rule to satisfy mechanically. If adding dependencies changes a mount-only effect into a loop, keep the effect mount-only and document why the suppression exists.

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

@@ -0,0 +1,41 @@
+```markdown
+# Coding Review
+
+## Result: APPROVE / REJECT
+
+## Summary
+{Summarize the review result in 1-2 sentences}
+
+## Current Iteration Findings (new)
+| # | finding_id | family_tag | Severity | Location | Issue | Impact | Fix Suggestion |
+|---|------------|------------|----------|----------|-------|--------|----------------|
+| 1 | CODE-NEW-src-file-L42 | bug | High / Medium / Low | `src/file.ts:42` | {Issue} | {Impact} | {Fix suggestion} |
+
+## Carry-over Findings (persists)
+| # | finding_id | family_tag | Previous Evidence | Current Evidence | Issue | Fix Suggestion |
+|---|------------|------------|-------------------|------------------|-------|----------------|
+| 1 | CODE-PERSIST-src-file-L77 | regression | `src/file.ts:77` | `src/file.ts:77` | {Unresolved issue} | {Fix suggestion} |
+
+## Resolved Findings (resolved)
+| finding_id | Resolution Evidence |
+|------------|---------------------|
+| CODE-RESOLVED-src-file-L10 | Resolved at `src/file.ts:10` |
+
+## Reopened Findings (reopened)
+| # | finding_id | family_tag | Prior Resolution Evidence | Recurrence Evidence | Issue | Fix Suggestion |
+|---|------------|------------|--------------------------|---------------------|-------|----------------|
+| 1 | CODE-REOPENED-src-file-L55 | bug | `Previously: src/file.ts:10` | `src/file.ts:55` | {Reopened issue} | {Fix suggestion} |
+
+## Verification Evidence
+- Diff review: {What was checked}
+- Build: {Result, or state unverified}
+- Tests: {Result, or state unverified}
+
+## Rejection Gate
+- REJECT only when at least one finding exists in `new`, `persists`, or `reopened`
+- Findings without `finding_id` are invalid
+```
+
+**Cognitive load reduction rules:**
+- APPROVE: Summary only (5 lines or fewer)
+- REJECT: Include only relevant finding rows (30 lines or fewer)

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

@@ -11,6 +11,7 @@
 |--------|--------|-------|
 | Component design | ✅ | - |
 | State management | ✅ | - |
+| Canonical and derived state | ✅ | - |
 | Performance | ✅ | - |
 | Accessibility | ✅ | - |
 | Type safety | ✅ | - |

package/builtins/en/facets/output-contracts/maintenance-scope.md

@@ -0,0 +1,29 @@
+```markdown
+# Maintenance Change Scope
+
+## Task
+{One-line task summary}
+
+## Required Changes
+| File | Reason | Requirement Mapping |
+|------|--------|---------------------|
+| {File} | {Reason} | {Mapped requirement} |
+
+## Related Changes
+| File | Reason | Relation to Required Change |
+|------|--------|-----------------------------|
+| {File} | {Reason} | {Relation} |
+
+## Existing Contracts Preserved
+| Contract | Target | Preservation |
+|----------|--------|--------------|
+| {Contract type} | {Target} | {What is preserved} |
+
+## Unnecessary Change Check
+| Check Target | Result | Notes |
+|--------------|--------|-------|
+| Renames or moves | {Present/none} | {Notes} |
+| UI copy or accessibility | {Present/none} | {Notes} |
+| Comment deletion | {Present/none} | {Notes} |
+| Test expectation changes | {Present/none} | {Notes} |
+```

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

@@ -0,0 +1,27 @@
+# Coding Reviewer
+
+You are a code reviewer for an AI coding agent. You read the task intent and diff, then identify concrete implementation bugs, regressions, security risks, and missing tests.
+
+## Role Boundaries
+
+**Do:**
+- Inspect the diff and nearby code
+- Check whether the implementation works for the task intent
+- Detect changes that break existing behavior
+- Detect failures in error handling, edge cases, persistence, concurrency, and external integration
+- Flag clear security or data-protection issues
+- Flag missing tests or verification when they matter
+
+**Don't:**
+- Write code yourself
+- Turn unsupported speculation into findings
+- Require preference-only refactors
+- Mix unrelated pre-existing issues into this review
+
+## Behavioral Principles
+
+- Ground findings in actual code, the diff, or execution evidence
+- Do not include findings with weak fix justification
+- Report higher-impact issues first
+- State location, impact, and fix direction briefly and concretely
+- Approve when there are no issues

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

@@ -138,7 +138,7 @@ When any of the following apply:
 - **Stop loops**: Suggest design revision for 3+ iterations
 - **Don't forget business value**: Value delivery over technical perfection
 - **Consider context**: Judge according to project situation
-- **Verify non-blocking classifications**: Always verify issues classified as "non-blocking," "existing problems," or "informational" by reviewers. If an issue in a changed file was marked as non-blocking, escalate it to blocking and REJECT
+- **Verify non-blocking classifications**: Always verify issues classified as "non-blocking," "existing problems," or "informational" by reviewers. If an issue in changed code or in an area directly related to correctness, contracts, or wiring of the change was marked as non-blocking, escalate it to blocking and REJECT
 - **Do not invent command outcomes**: If there is no execution evidence, treat it as unverified
 
 ## Execution Evidence

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

@@ -144,15 +144,74 @@ AI tends to over-deliver. Check for unnecessary additions.
 | Premature abstraction | Interfaces/abstractions for single implementations |
 | Over-configuration | Making things configurable that don't need to be |
 | Gold-plating | "Nice-to-have" additions not asked for |
+| Extra changes disguised as related work | Cleanup, renames, or moves justified only because they are near the edited code |
+| Incidental observable contract changes | Changing values observed by users or tests without being asked |
 | Unnecessary legacy support | Adding mapping/normalization logic for old values without explicit instruction |
 
 The best code is the minimum code that solves the problem.
 
+### Extra Changes Disguised as Related Work
+
+AI often justifies unnecessary cleanup as related work because it is "in the touched file", "near the same responsibility", or "more idiomatic". Whether a change is related is determined by causal necessity for the request, not by file proximity.
+
+| Pattern | Verdict |
+|---------|---------|
+| Renaming, moving, or responsibility changes justified only because the file was touched | REJECT |
+| Changing Props type names, return shapes, or public function names without direct implementation need | REJECT |
+| Deleting existing comments after assuming they are merely explanatory | REJECT |
+| Removing or weakening tested existing behavior just to make tests pass | REJECT |
+| Mixing framework-style improvements without explicit request | REJECT |
+| Adding parameters or updating call sites required to wire the new feature | OK |
+| Deleting old implementation that is genuinely no longer used | OK |
+
+Verification approach:
+1. Obtain the entire cumulative diff from the task's starting point (the base) and list renames, moves, deletions, responsibility changes, and test expectation changes (do not look only at the most recent fix; unrelated changes buried in earlier iterations do not appear in the latest fix report)
+2. For each change, ask whether the request fails without it
+3. Do not accept "more readable", "more idiomatic", or "cleanup while here" as necessity
+4. Revert changes whose necessity cannot be explained before completing the task
+
+### Incidental Observable Contract Changes
+
+AI often changes existing contracts under the banner of "improvement", "standardization", or "clarity" even when the task does not require it. UI copy, accessible names, event names, return values, error messages, log formats, public APIs, type names, file placement, comments, and behavior asserted by tests are observable contracts.
+
+| Pattern | Verdict |
+|---------|---------|
+| Contract change unrelated to the request | REJECT |
+| Tests are updated only to follow the new contract | REJECT |
+| 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 |
+
+Verification approach:
+1. Inspect changed strings, attributes, event names, return values, error messages, and log formats in the diff
+2. Check whether each one is directly required by the task
+3. If test expectations merely follow implementation changes, check whether the original contract can be preserved
+4. If the contract change is necessary, verify that reason and impact scope are explained
+
 Legacy support criteria:
 - Unless explicitly instructed to "support legacy values" or "maintain backward compatibility", legacy support is unnecessary
 - Do not add `.transform()` normalization, `LEGACY_*_MAP` mappings, or `@deprecated` type definitions
 - Support only new values and keep it simple
 
+### Over-Abstracting with Function Objects
+
+AI often turns a small number of concrete branches into config arrays, function objects, and generic loops to make the code look "extensible". The problem is not Strategy itself; the problem is hiding differences in data without naming the concept. A Strategy is useful when it names a domain concept and makes the replacement boundary explicit.
+
+| Pattern | Example | Verdict |
+|---------|---------|---------|
+| Single-use operation config array | Processing `[{ kind, fields, removedFields }]` in a loop | REJECT |
+| Deletions, side effects, or exception cases are hidden in config objects | Readers must inspect config values to find destructive behavior | REJECT |
+| Function object introduced when each branch is only 1-3 lines | `handlers[type]()` adds indirection only | REJECT |
+| Strategy represents a domain concept and clarifies the implementation boundary | `TaxPolicy`, `PaymentMethod`, `RetryStrategy` | OK |
+| Many branches share the same shape and are expected to grow | Consider a handler map | OK |
+
+Verification approach:
+1. Grep usage sites for added arrays, Maps, Strategies, or function objects
+2. If used in only one place, check whether explicit branching would be clearer
+3. Check whether side effects, deleted fields, or compatibility behavior are hidden in config objects
+4. Prefer `when` / `switch` when branch names sufficiently express domain meaning
+5. Allow Strategy when naming the concept improves understanding
+
 ## Premature Caching Strategy Introduction
 
 AI tends to proactively introduce caching mechanisms to "improve" performance. Do not add caching strategies until explicitly requested.

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

@@ -14,6 +14,7 @@ Prioritize correctness over speed, and code accuracy over ease of implementation
 | Boy Scout | Leave touched areas a little better than you found them |
 | Fail Fast | Detect errors early. Never swallow them |
 | Project scripts first | Use project-defined scripts for tool execution. Direct invocation is a last resort |
+| State normalization | Do not keep the same fact in multiple states |
 
 ## No Fallbacks or Default Arguments
 
@@ -183,6 +184,41 @@ const handlers = { A: handleA, B: handleB, C: handleC };
 handlers[type]?.();
 ```
 
+### Do Not Over-Abstract
+
+Use abstraction to reduce duplication and real axes of change, and also to name concepts so the code is easier to understand. Turning a few concrete operations into "config objects + function objects + loops" is not abstraction if it only makes domain differences harder to read.
+
+| Criteria | Judgment |
+|----------|----------|
+| A small number of branches differs by event type, state, or domain concept | Use explicit `when` / `switch` |
+| The same operation with the same argument shape repeats in 3+ places | Consider abstraction |
+| A config array or function object is used in only one place | REJECT. Prefer explicit branching first |
+| Side effects or removed fields cannot be understood without reading config objects | REJECT |
+| Strategy names a domain concept and makes interchangeable implementations explicit | OK |
+| Branch names read as domain concepts | OK |
+
+```typescript
+// ❌ Over-abstracted - readers must inspect both the config array and loop to see behavior
+const operations = [
+  { kind: 'create', normalize: ['owner'], remove: [] },
+  { kind: 'revise', normalize: ['owner'], remove: ['legacyOwner'] },
+]
+for (const operation of operations) {
+  applyOperation(record, operation)
+}
+
+// ✅ When branch meaning matters, make it explicit
+switch (record.kind) {
+  case 'create':
+    normalizeOwner(record)
+    break
+  case 'revise':
+    removeLegacyOwner(record)
+    normalizeOwner(record)
+    break
+}
+```
+
 ### Keep Abstraction Levels Consistent
 
 Within a single function, keep operations at the same granularity. Extract detailed operations into separate functions. Do not mix "what to do" with "how to do it."
@@ -319,11 +355,56 @@ Dependencies and triggers must match the conditions under which the behavior sho
 | Rerun conditions correspond to URL, filters, explicit refresh actions, or other intended behavior | OK |
 | Initialization and later refetch triggers are designed separately | OK |
 
+## Contract Change Consistency
+
+When changing contracts that other code or users depend on — types, interfaces, APIs, config schemas, persistence formats, events, or file formats — keep definitions, producers, consumers, and verification aligned in the same change.
+
+| Criteria | Judgment |
+|----------|----------|
+| Only the contract definition is changed, while callers, producers, or readers are not updated | REJECT |
+| A new argument, field, or config value is added but there is no route to pass it to consumers | REJECT |
+| Fields or values not present in the documented schema/config format are used | REJECT |
+| Mocks, fixtures, or test data return shapes that differ from the real contract | REJECT |
+| The contract change and updates to callers, producers, and tests are made in the same change | OK |
+
 ## State Management
 
 - Confine state to where it is used
 - Children do not modify state directly (notify parents via events)
 - State flow is unidirectional
+- Do not keep derived values that can be computed from canonical state as independent state
+- If multiple fields require constant synchronization, revisit the state model
+
+| Criteria | Judgment |
+|----------|----------|
+| A value that can always be computed from one state is kept as another state | REJECT |
+| Multiple states have invariants that must always stay in sync | REJECT |
+| Persistence, sending, or diffing depends on derived values | REJECT |
+| Only canonical state is stored, and derived values are generated at use sites or boundaries | OK |
+
+## Unfinished Code
+
+Do not leave TODO/FIXME comments, empty implementations, stubs, or commented-out old implementations as substitutes for completed code. Implement what is needed now and delete what is not needed.
+
+| Criteria | Judgment |
+|----------|----------|
+| TODO/FIXME without an issue number, external blocker, and removal condition | REJECT |
+| Authorization, validation, persistence, or error handling is deferred with TODO | REJECT |
+| Empty implementations, `return null`, `pass`, or commented-out old implementations remain | REJECT |
+| An external dependency or known blocker makes implementation impossible now, with issue number and removal condition documented | Acceptable |
+| TODO only for future extension | REJECT |
+
+## Sensitive Information Handling
+
+Do not expose passwords, tokens, API keys, session IDs, auth headers, personal information, or other sensitive data in code, logs, error responses, or test output.
+
+| Criteria | Judgment |
+|----------|----------|
+| Sensitive data is hardcoded in source code or config files | REJECT |
+| Logs, exceptions, error responses, or test snapshots contain sensitive data | REJECT |
+| Whole requests or DTOs are logged and may include sensitive fields | REJECT |
+| Sensitive fields are explicitly omitted or masked | OK |
+| Debug logs include personal data but are assumed disabled in production | Warning. Verify it cannot leak through misconfiguration |
 
 ## Error Handling
 
@@ -486,10 +567,11 @@ Verification approach:
 - **Fallbacks are prohibited by default** - Do not write fallbacks using `?? 'unknown'`, `|| 'default'`, or swallowing via `try-catch`. Propagate errors upward. If absolutely necessary, add a comment explaining why
 - **Explanatory comments** - Express intent through code. Do not write What/How comments
 - **Unused code** - Do not write "just in case" code
+- **Unfinished code** - Do not leave TODO/FIXME without an issue number, external blocker, and removal condition; do not leave stubs or commented-out old code
 - **any type** - Do not break type safety
 - **Direct mutation of objects/arrays** - Create new instances with spread operators
 - **console.log** - Do not leave in production code
-- **Hardcoded secrets**
+- **Sensitive information exposure** - Do not include sensitive data in hardcoded values, logs, error responses, or test output
 - **Scattered hardcoded contract strings** - File names and config key names must be defined as constants in one place. Scattered literals are prohibited
 - **Scattered try-catch** - Centralize error handling at the upper layer
 - **Unsolicited backward compatibility / legacy support** - Not needed unless explicitly instructed
@@ -497,6 +579,6 @@ Verification approach:
 - **Replaced code surviving after refactoring** - Remove replaced code and exports. Do not keep unless explicitly told to
 - **Workarounds that bypass safety mechanisms** - If the root fix is correct, no additional bypass is needed
 - **Direct tool execution bypassing project scripts** - `npx tool` and similar bypass the lockfile, causing version mismatches. Look for project-defined scripts (npm scripts, Makefile, etc.) first. Only consider direct execution when no script exists
-- **Missing wiring** - When adding new parameters or fields, grep the entire call chain to verify. If callers do not pass the value, `options.xxx ?? fallback` always uses the fallback
+- **Missing wiring** - When adding new parameters or fields, search the entire call chain to verify. If callers do not pass the value, `options.xxx ?? fallback` always uses the fallback
 - **Redundant conditionals** - When if/else calls the same function with only argument differences, unify using ternary operators or spread syntax
-- **Copy-paste patterns** - Before writing new code, grep for existing implementations of the same kind and follow the existing pattern. Do not introduce your own style
+- **Copy-paste patterns** - Before writing new code, search for existing implementations of the same kind and follow the existing pattern. Do not introduce your own style