mustflow 1.15.97

package/templates/default/locales/ko/.mustflow/skills/composition-over-inheritance/SKILL.md

@@ -0,0 +1,176 @@
+---
+mustflow_doc: skill.composition-over-inheritance
+locale: ko
+canonical: false
+revision: 4
+lifecycle: mustflow-owned
+authority: procedure
+name: composition-over-inheritance
+description: Apply this skill when code introduces, extends, reviews, or refactors class inheritance, base classes, abstract classes, template methods, protected state, mixins, framework subclasses, or subtype hierarchies, especially when behavior reuse, feature variants, provider implementations, policies, strategies, adapters, or test seams could be expressed with composition instead.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.composition-over-inheritance
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - test_related
+    - test
+    - lint
+    - build
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Composition Over Inheritance
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Treat inheritance as an exception, not the default way to reuse implementation. Prefer explicit collaborators: small role objects, functions, policies, strategies, adapters, state machines, decorators, and injected dependencies.
+
+The goal is to keep change dimensions separate, avoid fragile parent-child coupling, make tests easy to assemble, and prevent subclass counts from growing with every feature combination.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- New code introduces `extends`, `abstract class`, `Base*`, `Abstract*`, `Common*`, `Core*`, mixins, template methods, `protected` fields, or deep class hierarchies.
+- Existing code is being refactored from inheritance, template methods, no-op overrides, or shared base classes.
+- A feature has multiple change dimensions such as format, storage, notification, provider, environment, permission policy, pricing policy, state transition, or retry behavior.
+- Framework code requires subclassing, but business logic should stay outside the framework subclass.
+- Tests are hard to write because parent setup, `super()` order, protected state, or subclass-specific behavior is entangled.
+- The design could use strategy objects, policy objects, adapters, decorators, state machines, discriminated unions, functions, or dependency injection instead of inheritance.
+- State-specific subclasses are proposed or already exist to represent lifecycle behavior that could be expressed as an explicit transition table.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The code has no inheritance, base-class, subtype, or behavior-combination decision.
+- The inheritance is a shallow and conventional language or ecosystem type, such as `Error`, `Exception`, a required test framework base class, or a required framework lifecycle class.
+- The task is only about external provider boundaries; use `adapter-boundary`.
+- The task is only about hidden dependency construction or global lookup; use `dependency-injection`.
+- The task is a pure data or function refactor where no type hierarchy or collaborator split is being considered.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- The class or module under change and any existing inheritance chain, base class, template method, mixin, or protected state.
+- The behavior that needs reuse and the change dimensions that may vary independently.
+- Local patterns for functions, policies, strategies, adapters, state machines, decorators, dependency injection, and tests.
+- Compatibility constraints: public API, framework inheritance requirements, migration wrappers, and existing tests.
+- Relevant command-intent contract entries for tests, builds, docs, templates, release metadata, and mustflow validation.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+- The intended behavior is understood well enough to avoid changing semantics while changing structure.
+- If the existing area is unfamiliar, use `pattern-scout` or `codebase-orientation` before changing type boundaries.
+- If the refactor must preserve behavior, use `behavior-preserving-refactor` together with this skill.
+- If multiple algorithms, policies, scoring methods, pricing rules, provider choices, or feature variants share one purpose, use `strategy-pattern` before inventing subclasses.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Replace implementation inheritance with functions, role interfaces, policies, strategies, adapters, decorators, state machines, discriminated unions, or small orchestrating objects.
+- Keep required framework subclasses thin and delegate business behavior to injected use cases or collaborators.
+- Add temporary compatibility wrappers when needed for a safe migration away from existing subclasses.
+- Add focused tests or fixtures that lock current behavior before changing inheritance structure.
+- Do not create broad `Base`, `Abstract`, `Common`, `Core`, or `Manager` classes to share miscellaneous methods.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Identify why inheritance is present or being proposed.
+   - Allowed reasons: required framework base class, conventional error or exception type, required test framework base class, sealed or closed type hierarchy, or a true substitutable subtype relationship.
+   - Suspicious reasons: sharing common methods, toggling optional behavior, swapping providers, reducing conditionals, hiding setup, reusing validation, or grouping unrelated helpers.
+2. Apply the substitution check before keeping inheritance.
+   - A child must be safe everywhere the parent is expected.
+   - The child must not require stricter inputs, return weaker outputs, no-op parent behavior, throw for normal parent methods, or require callers to check `instanceof`, class name, kind, mode, or type before use.
+3. Count independent change dimensions.
+   - If format, storage, notification, provider, policy, environment, permission, state, retry, logging, caching, or transport can change independently, do not encode the combination as subclasses.
+   - Split each meaningful dimension into a role object, function, strategy, policy, adapter, decorator, state machine, or data field.
+4. Inspect the inheritance depth and coupling.
+   - Application code should have inheritance depth 0 or 1.
+   - Reject chains where behavior depends on `super()` order, parent constructor side effects, protected mutable state, or parent methods calling overridable child methods.
+5. Replace shared implementation with simpler composition first.
+   - Use pure functions for stateless calculations and formatting.
+   - Use role objects for replaceable collaborators.
+   - Use policy objects for business decisions.
+   - Use strategy objects for algorithms, policies, scoring methods, provider choices, and feature variants. Use `strategy-pattern` before adding or refactoring a strategy family.
+   - Use facade objects for stable high-level subsystem entry points that coordinate several collaborators. Use `facade-pattern` before adding or refactoring a facade.
+   - Use adapters for external services and provider-specific data.
+   - Use decorators for cross-cutting behavior such as logging, caching, retry, rate limiting, timing, and authorization.
+   - Use state machines or transition tables when state controls allowed actions. Use `state-machine-pattern` before editing lifecycle state transitions, status fields, guards, terminal states, or transition effects.
+   - Use discriminated unions or sealed types for closed data variants when the language supports them.
+6. Keep orchestration explicit. A composed object may own the workflow, but it should delegate each variable behavior to a collaborator rather than reaching into subclass hooks.
+7. Keep construction outside the core object when collaborators are replaceable or external. If the change introduces injected collaborators, apply `dependency-injection`; if those collaborators cross provider or protocol boundaries, also apply `adapter-boundary`.
+8. Keep framework subclasses thin when inheritance is unavoidable.
+   - They may parse requests, extract framework context, call use cases, and map responses.
+   - They should not contain domain policy, external API calls, database queries, complex state transitions, or provider-specific translation.
+9. Use temporary wrappers only for migration.
+   - A legacy subclass may delegate to a new composed implementation to preserve public API.
+   - New code should use the composed implementation directly.
+   - Remove wrappers after callers have migrated.
+10. Guard against over-composition.
+    - Do not create interfaces for one-line pure functions, stable internal helpers, or single implementations with no external boundary and no test replacement need.
+    - If every class only delegates once, constructor setup becomes harder than the business logic, or a dependency object becomes broad, simplify.
+11. Protect behavior with tests.
+    - Before refactoring an inheritance tree, add or reuse tests around the observable behavior.
+    - Prefer fake collaborators over parent-state setup.
+    - Add tests for each extracted policy, strategy, adapter, decorator, or state transition when the behavior is meaningful.
+12. Verify with the narrowest configured command intents that cover changed source, tests, templates, docs, release metadata, and mustflow checks.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- New application code does not add inheritance for implementation reuse.
+- Any remaining inheritance is shallow, justified, and isolated to framework, error, test, or closed-type cases.
+- Shared behavior lives in functions, role objects, policies, strategies, adapters, decorators, state machines, or explicit data structures.
+- Variable behavior is selected by composition rather than subclass explosion.
+- There is no protected mutable state, no-op override, parent-child type check, or `super()` call-order dependency in core logic.
+- Tests can replace collaborators without constructing a fragile parent hierarchy.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `test_related`
+- `test`
+- `lint`
+- `build`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Prefer the narrowest configured test or build intent that proves the affected behavior. Use documentation and release checks when skill routes, templates, public docs, package metadata, or installed-file surfaces change.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If inheritance is required by a framework, keep the subclass as an adapter and move business behavior to composed collaborators.
+- If an inheritance refactor would break public API, add a temporary wrapper and report the migration path.
+- If extracted collaborators are too many or too vague, collapse them into fewer functions or role objects with clearer ownership.
+- If tests require protected state or parent internals, add higher-level behavior tests before changing structure.
+- If a class still needs many collaborators after composition, look for mixed responsibilities and split the use case rather than adding a broad dependency bag.
+- If local language features make a sealed hierarchy or discriminated union clearer than strategy objects, use the simpler closed-data representation and report why.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Inheritance or base-class surface reviewed
+- Reason for keeping or replacing inheritance
+- Change dimensions identified
+- Composition pattern selected
+- Framework or error inheritance exceptions, if any
+- Collaborators, functions, policies, strategies, facades, adapters, decorators, or state machines added or reused
+- Temporary compatibility wrappers, if any
+- Tests added or reused
+- Command intents run
+- Skipped checks and reasons
+- Remaining inheritance or composition risk

package/templates/default/locales/ko/.mustflow/skills/contract-sync-check/SKILL.md

@@ -0,0 +1,116 @@
+---
+mustflow_doc: skill.contract-sync-check
+locale: ko
+canonical: false
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: contract-sync-check
+description: 코드, 스키마, 템플릿, 테스트, 문서 사이에 맞춰져야 하는 선언된 계약에 변경이 영향을 줄 때 적용합니다.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.contract-sync-check
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# 계약 동기화 확인
+
+<!-- mustflow-section: purpose -->
+## 목적
+
+선언된 동작, 기계가 읽는 계약, 설치 템플릿, 테스트, 공개 문서가 변경 뒤 서로 어긋나지 않게 합니다.
+
+<!-- mustflow-section: use-when -->
+## 사용할 때
+
+- 명령, 옵션, JSON 출력, 스키마, 템플릿 파일, 매니페스트, 잠금 항목, 선호값, 공개 문서가 바뀝니다.
+- mustflow가 소유한 파일을 추가, 삭제, 이름 변경, 재분류합니다.
+- 테스트가 패키지, 템플릿, 스키마, 명령, 대시보드, 문서 동작을 기대값으로 고정합니다.
+- 사용자가 문서, 설정, 설치 템플릿 동작도 함께 바꿔야 하는지 묻습니다.
+
+<!-- mustflow-section: do-not-use-when -->
+## 사용하지 않을 때
+
+- 선언된 계약이나 공개 표면이 없는 내부 구현 리팩터링입니다.
+- 변경 파일이 더 좁은 스킬로 이미 덮이고, 그 절차가 영향을 받는 계약을 모두 확인합니다.
+- 사용자가 공개 또는 설치 표면을 갱신하지 않는 로컬 실험을 명시적으로 요청했습니다.
+
+<!-- mustflow-section: required-inputs -->
+## 필요한 입력
+
+- 변경 파일 목록과 의도한 동작 변경.
+- 코드, 스키마, 설정, 템플릿 메타데이터, 문서 같은 기본 계약 출처.
+- 알려진 파생 표면: 테스트, README, 문서 사이트, 지역화 템플릿, 매니페스트, 잠금 파일, JSON 스키마.
+- 관련 명령 의도 계약 항목.
+
+<!-- mustflow-section: preconditions -->
+## 전제 조건
+
+- 작업이 사용할 때 조건에 맞고 사용하지 않을 때 조건에는 해당하지 않습니다.
+- 필요한 입력이 있거나, 부족한 입력을 추측하지 않고 보고할 수 있습니다.
+- 현재 범위의 상위 지시와 `.mustflow/config/commands.toml`을 확인했습니다.
+
+<!-- mustflow-section: allowed-edits -->
+## 허용되는 수정
+
+- 계약을 일관되게 유지하는 데 필요한 표면만 갱신합니다.
+- 변경된 계약이나 패키징 표면을 고정할 때만 테스트를 추가하거나 조정합니다.
+- 정확한 문구를 자신 있게 지역화할 수 없으면 번역이나 문장 중심 문서를 검수 대상으로 표시합니다.
+- 명령 권한을 넓히거나, 새 계약 파일을 지어내거나, 탐색 메모를 구속력 있는 정책으로 바꾸지 않습니다.
+
+<!-- mustflow-section: procedure -->
+## 절차
+
+1. 변경되는 계약의 이름을 붙이고 기준 출처를 확인합니다.
+2. 그 계약에 맞춰야 하는 표면을 나열합니다. 예: 소스 코드, 스키마, 명령 메타데이터, 템플릿, 매니페스트, 잠금 파일, 테스트, README, 문서 사이트, 지역화 사본.
+3. 변경 파일 목록을 그 표면 목록과 비교하고 빠진 필수 표면을 추가합니다.
+4. 파생 파일은 기준 출처와 기계적으로 맞춥니다. 일부 표면을 의도적으로 갱신하지 않았다면 이유를 기록합니다.
+5. 명령 의도 이름, 스키마 식별자, 앞부분 메타데이터 리비전, 템플릿 항목, 버전 문자열, 문서 예시가 일치해야 하는 곳에서 정확히 일치하는지 확인합니다.
+6. 계약과 건드린 패키징 또는 문서 표면을 덮는 가장 좁은 구성된 검증을 사용합니다.
+7. 최종 보고에서 동기화한 표면과 건너뛰거나 미룬 표면을 구분합니다.
+
+<!-- mustflow-section: postconditions -->
+## 완료 조건
+
+- 계약 기준 출처와 필요한 모든 파생 표면이 일치합니다.
+- 의도적으로 오래 두거나 미루거나 검수가 필요한 표면을 명시합니다.
+- 최종 보고에는 계약 정합성 검증에 사용한 명령 의도가 포함됩니다.
+
+<!-- mustflow-section: verification -->
+## 검증
+
+사용 가능한 구성된 일회성 명령 의도를 사용합니다.
+
+- `changes_status`
+- `changes_diff_summary`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+계약이 실행 동작에 영향을 주면 더 좁은 구성된 테스트나 빌드 의도도 실행합니다.
+
+<!-- mustflow-section: failure-handling -->
+## 실패 처리
+
+- 검증에서 불일치가 나오면 새 동작을 더하기 전에 첫 계약 불일치부터 고칩니다.
+- 기준 출처가 불분명하면 조용히 하나를 고르지 말고 경쟁하는 출처를 보고합니다.
+- 필요한 표면이 현재 작업에서 검증하기에 너무 넓으면 건너뛴 표면과 위험을 보고합니다.
+- 지역화 표면을 자신 있게 갱신할 수 없으면 출처 메타데이터를 정확히 유지하고 번역을 검수 대상으로 표시합니다.
+
+<!-- mustflow-section: output-format -->
+## 출력 형식
+
+- 변경된 계약
+- 사용한 기준 출처
+- 동기화한 표면
+- 미루었거나 검수가 필요한 표면
+- 실행한 명령 의도
+- 건너뛴 검증과 이유
+- 남은 불일치 위험

package/templates/default/locales/ko/.mustflow/skills/date-number-audit/SKILL.md

@@ -0,0 +1,116 @@
+---
+mustflow_doc: skill.date-number-audit
+locale: ko
+canonical: false
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: date-number-audit
+description: 날짜, 버전, 개수, 기간, 한도, 지표, 벤치마크, 가격, 비율 또는 다른 숫자 사실을 만들거나 수정하거나 보고할 때 적용합니다.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.date-number-audit
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# 날짜와 숫자 검수
+
+<!-- mustflow-section: purpose -->
+## 목적
+
+코드, 문서, 테스트, 최종 보고가 날짜와 숫자 사실을 지어내거나 오래된 값을 복사하거나 서로 맞지 않게 두지 않도록 합니다.
+
+<!-- mustflow-section: use-when -->
+## 사용할 때
+
+- 날짜, 마감일, 릴리스 버전, 개수, 기간, 제한 시간, 한도, 할당량, 크기, 비율, 가격, 벤치마크, 점수, 테스트 커버리지 값, 생성 파일 총계를 추가, 수정, 제거, 보고합니다.
+- 문서가 명령, 파일, 페이지, 템플릿, 언어, 테스트, 검사, 지원 항목의 개수를 요약합니다.
+- 최종 보고나 사용자에게 보이는 문구가 코드, 템플릿, 패키지, 문서, 생성 출력 변경 뒤에 달라질 수 있는 숫자에 의존합니다.
+- 실패한 검사가 오래된 리비전, 맞지 않는 버전, 잘못된 개수, 지난 날짜, 일관되지 않은 숫자 기준을 가리킵니다.
+
+<!-- mustflow-section: do-not-use-when -->
+## 사용하지 않을 때
+
+- 숫자가 공개 의미나 파일 간 의미가 없는 지역 변수, 반복문 인덱스, 열거형 값, 테스트 fixture입니다.
+- 작업이 기존 숫자 문구를 그대로 보존할 뿐 그 값에 의존하지 않습니다.
+- 릴리스 버전, 의존성 실재 확인, 산출물 무결성, 출처 최신성에 관한 더 좁은 스킬이 맞습니다.
+
+<!-- mustflow-section: required-inputs -->
+## 필요한 입력
+
+- 날짜 또는 숫자 사실과 그것을 말하거나, 파생하거나, 검증하는 모든 표면.
+- 패키지 메타데이터, 템플릿 메타데이터, 스키마, 코드 상수, 생성 출력, 테스트 단언, 현재 명령 결과 같은 값의 기준 출처.
+- 값이 근사치, 표본, 로컬 전용, 시간에 민감한 정보일 때 허용되는 정밀도와 표현.
+- 문서, 패키징, 빌드, mustflow 검증에 관한 명령 의도 계약 항목.
+
+<!-- mustflow-section: preconditions -->
+## 전제 조건
+
+- 작업이 사용할 때 조건에 맞고 사용하지 않을 때 조건에는 해당하지 않습니다.
+- 필요한 입력이 있거나, 부족한 입력을 추측하지 않고 보고할 수 있습니다.
+- 현재 범위의 상위 지시와 `.mustflow/config/commands.toml`을 확인했습니다.
+
+<!-- mustflow-section: allowed-edits -->
+## 허용되는 수정
+
+- 날짜와 숫자 사실을 원본 파일, 생성 메타데이터, 테스트, 문서, 최종 보고 사이에서 맞춥니다.
+- 정확한 숫자가 안정적이지 않다면 범위를 둔 표현이나 출처가 드러나는 표현으로 바꿉니다.
+- 문서를 채워 보이게 하려고 숫자를 지어내지 않습니다.
+- 작업과 기준 출처가 뒷받침하지 않으면 동작 기준값, 제한 시간, 한도, 릴리스 버전을 바꾸지 않습니다.
+
+<!-- mustflow-section: procedure -->
+## 절차
+
+1. 작업이 만들거나 수정하거나 보고하는 날짜와 숫자 사실을 나열합니다.
+2. 의존 표면을 바꾸기 전에 각 값의 기준 출처를 확인합니다.
+3. 관련 코드, 템플릿, 문서, 스키마, 테스트, 생성 메타데이터에서 같은 값을 중복해서 말하는 곳을 찾습니다.
+4. 기준 출처에 맞춰 의존 표면을 갱신하거나, 정확한 검증이 불가능하면 근사치, 로컬 값, 표본, 미검증 값으로 표시합니다.
+5. 버전 번호, 템플릿 리비전, 스키마 리비전, 언어별 원문 리비전, 패키지 단언, 공개 예시를 함께 맞춥니다.
+6. 불확실성이 실제로 있고 도움이 될 때만 "약", "현재", "이 확인 시점 기준", "최신 생성 출력 기준" 같은 표현을 씁니다.
+7. 값과 의존 표면이 여전히 일치함을 증명하는 가장 좁은 구성된 검증을 실행합니다.
+
+<!-- mustflow-section: postconditions -->
+## 완료 조건
+
+- 공개되거나 파일 간에 의미가 있는 모든 날짜와 숫자 사실에는 이름 붙인 기준 출처나 명시한 불확실성 설명이 있습니다.
+- 숫자를 단언하는 테스트와 메타데이터가 변경된 기준 출처와 맞습니다.
+- 최종 보고는 의도적으로 근사치나 미검증 상태로 둔 값을 밝힙니다.
+
+<!-- mustflow-section: verification -->
+## 검증
+
+사용 가능한 구성된 일회성 명령 의도를 사용합니다.
+
+- `changes_status`
+- `changes_diff_summary`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+변경된 숫자 표면을 더 잘 증명하는 좁은 테스트, 빌드, 문서 의도가 있으면 그 의도를 사용합니다.
+
+<!-- mustflow-section: failure-handling -->
+## 실패 처리
+
+- 두 출처가 다르면 추측하지 않습니다. 더 높은 권위의 출처를 확인하거나 충돌을 보고합니다.
+- 값이 시간, 네트워크 상태, 패키지 저장소 상태, 생성 출력, 외부 데이터에 의존하지만 새로 확인하지 않았다면 그 경계를 밝힙니다.
+- 정확한 숫자가 필요 없고 최신으로 유지하기 비싸다면 깨지기 쉬운 정밀도를 피하도록 문장을 바꿉니다.
+- 숫자 변경이 동작에 영향을 준다면 계속하기 전에 관련 코드, 테스트, 릴리스, 의존성 스킬을 적용합니다.
+
+<!-- mustflow-section: output-format -->
+## 출력 형식
+
+- 검수한 날짜 또는 숫자 사실
+- 각 값의 기준 출처
+- 맞춘 표면
+- 바꾼 정확한 값 또는 근사 표현으로 바꾼 값
+- 실행한 명령 의도
+- 건너뛴 검사와 이유
+- 남은 날짜 또는 숫자 위험

package/templates/default/locales/ko/.mustflow/skills/dependency-injection/SKILL.md

@@ -0,0 +1,161 @@
+---
+mustflow_doc: skill.dependency-injection
+locale: ko
+canonical: false
+revision: 3
+lifecycle: mustflow-owned
+authority: procedure
+name: dependency-injection
+description: Apply this skill when core or application logic creates, imports, resolves, or hides external dependencies such as databases, APIs, SDKs, filesystems, clocks, random generators, identifiers, loggers, configuration, framework request objects, AI clients, queues, or payment/email providers.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.dependency-injection
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - test_related
+    - test
+    - lint
+    - build
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Dependency Injection
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Keep business logic from creating, finding, or importing the tools it needs. External-world objects belong at assembly boundaries; core logic receives narrow ports, explicit values, or request context from the outside.
+
+Dependency injection is not an abstraction quota. Use it to keep replaceable infrastructure, hidden global state, and side effects from leaking into domain and use-case code.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- Core, domain, application, service, or use-case code directly constructs a database client, external SDK, queue, file storage, logger, clock, random generator, identifier generator, AI model client, email sender, payment gateway, HTTP client, or framework object.
+- Code reads `process.env`, current time, random values, UUIDs, files, local storage, global containers, or global loggers away from the assembly boundary.
+- A refactor aims to make behavior easier to test without real databases, network calls, API keys, filesystem writes, current time, or random identifiers.
+- New ports, adapters, provider modules, transaction runners, or composition roots are being introduced.
+- A function's signature hides required collaborators or accepts broad technical objects instead of the narrow capability it actually needs.
+- An optional collaborator should be wired as a real implementation or a safe null, no-op, disabled, identity, empty, deny-all, or failing implementation at the assembly boundary.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The code is a pure function, value object, entity constructor, small data formatter, or internal helper with no external dependency.
+- The task is a disposable one-off script that is not imported, tested, repeated, used in production, or connected to external services.
+- A framework's dependency injection mechanism is already confined to the application boundary and does not leak into domain code.
+- The only change needed is to confirm a package or tool exists; use `dependency-reality-check`.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- The target code area and the direct dependency, global state, or hidden collaborator being introduced or removed.
+- The intended business capability and which layer owns the rule: domain, application, infrastructure, adapter, route, worker, or assembly root.
+- Existing local patterns for ports, adapters, fakes, transaction runners, clocks, configuration loading, and test setup.
+- Current changed files and command-intent contract entries relevant to tests, builds, docs, release metadata, and mustflow validation.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Higher-priority instructions and `.mustflow/config/commands.toml` have been checked for the current scope.
+- If the local structure is unfamiliar, use `pattern-scout` or `codebase-orientation` before introducing new folders or naming conventions.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Define narrow consumer-owned ports where core logic needs external behavior.
+- Move concrete client creation, environment reads, lifecycle setup, and disposal to assembly boundaries.
+- Add infrastructure adapters that implement the ports and translate external rows, responses, errors, and identifiers into internal types.
+- Add local fakes, fixed clocks, fixed identifiers, and contract tests when needed to preserve behavior.
+- Wire optional collaborators with `null-object-pattern` when absence is explicit, safe, and should not leak nullable checks into business logic.
+- Do not add a service locator, global container access, broad application dependency bag, framework decorator in domain code, or speculative interface for every class.
+- When the dependency also crosses an external protocol, provider, database, webhook, queue, file, cache, AI model, or framework boundary, use `adapter-boundary` for the translation and failure-handling rules.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Classify the code under change:
+   - Core logic: domain rules, use cases, state transitions, policy checks, calculations, and business decisions.
+   - Edge logic: routes, controllers, workers, command handlers, adapters, repositories, SDK wrappers, and assembly roots.
+2. Find direct external dependencies before editing. Look for concrete SDK construction, database clients, HTTP clients, file APIs, environment reads, current-time calls, random or UUID generation, global loggers, global containers, framework request or response objects, and external error types.
+3. Decide whether dependency injection is warranted. Inject only collaborators that cross a boundary, are hard to test, may change implementation, or represent hidden global state. Do not wrap pure helpers, value objects, or stable internal data structures just to add ceremony.
+4. Define ports from the consumer's need, not from the provider's API.
+   - Prefer `PaymentGateway`, `UserRepository`, `EmailSender`, `ImageStorage`, or `TextGenerator`.
+   - Avoid provider-shaped ports such as `StripeService`, `PrismaUserStore`, `ResendMailer`, `S3ImageStorage`, or `OpenAITextGenerator` at the core boundary.
+5. Choose the injection style:
+   - Use constructor injection or a dependency object for classes with stable collaborators.
+   - Use function-closure injection for small use cases or function-oriented modules.
+   - Use method parameters for per-call data such as actor, tenant, locale, request id, pagination, filters, or command input.
+   - Use factories only when runtime values decide the implementation, lifecycle, or resource handle.
+6. Keep construction at the assembly boundary. Create concrete clients, load and validate configuration, register containers, open connections, and wire adapters in files such as bootstrap, server setup, worker setup, route setup, module registration, or test setup.
+   - If a dependency is optional and disabled by explicit configuration, choose the real collaborator or the safe neutral implementation here, not inside business logic.
+   - If a dependency is required, validate configuration here and fail early instead of injecting a null object.
+7. Treat time, random values, identifiers, configuration, logging, transactions, and framework objects as dependencies.
+   - For domain decisions, prefer an already captured instant or time context over passing a clock that can be queried inside the domain.
+   - Pass fixed implementations in tests so time, identifiers, and random choices are reproducible.
+8. Keep adapters responsible for translation. Repositories and provider adapters should convert database rows, external responses, external errors, and provider identifiers before returning to core logic.
+9. If the injected collaborator is an external boundary, apply `adapter-boundary` before finalizing the port and adapter. Dependency injection decides how core logic receives the collaborator; adapter boundaries decide how external protocols, data, errors, timeouts, retries, idempotency, security, and observability are translated.
+10. Keep transaction ownership explicit. Inject a transaction runner when a use case needs atomic persistence across multiple repositories. Do not hide transaction boundaries inside repositories when the use case owns the unit of work, and do not call external APIs inside a database transaction.
+11. Reject hidden dependency patterns:
+    - no property injection for required collaborators
+    - no service locator or `container.resolve` in core logic
+    - no process-wide mutable singleton holding request state
+    - no broad `AppDeps` object when a use case needs only a few collaborators
+    - no circular service dependencies unless a smaller use case, shared policy, or event boundary has been considered first
+12. Keep tests honest. Unit tests for core logic should use fakes or fixed collaborators and should not require a real database, real network, real API key, real email, real payment, real filesystem side effect, current time, or random UUID. Test real adapters separately with integration or contract coverage.
+13. Verify with the narrowest configured command intents that cover the changed code, tests, template files, docs, and release metadata.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Core logic declares its collaborators through constructor parameters, function parameters, or narrow context objects.
+- Concrete external implementation creation is easy to find at assembly boundaries.
+- Core logic does not import provider SDKs, database clients, framework request or response objects, global containers, or external provider error types.
+- Tests can replace external collaborators, time, identifiers, and random values without live infrastructure.
+- Adapter boundaries translate external data and failures before they reach core logic.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `test_related`
+- `test`
+- `lint`
+- `build`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Prefer the narrowest configured test or build intent that proves the affected boundary. Use documentation and release checks when templates, skill routes, public docs, package metadata, or installed-file surfaces change.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If extracting a port would duplicate an existing local interface, reuse or narrow the existing local pattern instead of creating a parallel abstraction.
+- If a class needs many collaborators, stop before adding a giant dependency object and look for mixed responsibilities, smaller use cases, or adapter boundaries.
+- If a framework forces decorators or container registration, keep that integration in the application boundary and do not let it shape domain types.
+- If a direct dependency cannot be removed in one safe step, first wrap it at the smallest local boundary and report the remaining leakage.
+- If tests still need real infrastructure after the refactor, report which dependency is still not injectable and why.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Dependency boundary reviewed
+- Direct external dependencies found
+- Injection style selected
+- Ports and adapters added or reused
+- Assembly boundary used
+- External data or error translation handled
+- Tests, fakes, or fixed collaborators added or reused
+- Command intents run
+- Skipped checks and reasons
+- Remaining dependency leakage or lifecycle risk