mustflow 2.27.0 → 2.29.0

package/templates/default/locales/en/.mustflow/skills/structure-first-engineering/SKILL.md

@@ -0,0 +1,205 @@
+---
+mustflow_doc: skill.structure-first-engineering
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: structure-first-engineering
+description: Apply this skill as an adjunct for non-trivial code changes where early structure decisions affect domain rules, public contracts, external I/O, operational safety, testability, error handling, concurrency, data flow, or future change cost.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.structure-first-engineering
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - test_related
+    - test
+    - lint
+    - build
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Structure-First Engineering
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Make structural decisions before coding when the wrong boundary would be expensive to unwind.
+
+This skill is not anti-abstraction. It assumes high-quality structure can be cheap to create with
+LLM help, while late boundary repair can be expensive. Invest early in hard-to-reverse boundaries,
+but reject abstractions that do not lower change cost, failure risk, or cognitive load.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A code task changes domain rules, public contracts, external I/O, persistence, authorization, concurrency, operational behavior, or error semantics.
+- A task needs a new module boundary, use case, adapter, DTO, schema, state transition, result type, provider boundary, or testable core.
+- The user asks to think like a senior or long-experienced engineer, design well up front, avoid later rewrites, or prevent structural debt.
+- A proposed implementation could mix validation, transformation, domain decisions, I/O, formatting, and output mapping in one place.
+- A change could create hard-to-reverse coupling to a framework, provider response, database shape, CLI/API schema, local filesystem, time, randomness, environment, process memory, queue, webhook, or worker behavior.
+- A bug fix reveals that failures, retries, partial success, or duplicated effects are not modeled clearly.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task is a surface-only documentation, copy, comment, log wording, or UI text change with no execution-path risk.
+- A narrow pattern skill is already sufficient and the risk block would add no new decision.
+- The user explicitly asks for analysis-only code review; use `code-review` or `architecture-deepening-review` unless implementation will follow.
+- The task is a tiny local logic change with obvious inputs, outputs, tests, and no contract or I/O boundary.
+- The proposed structure is only a file split, naming wrapper, `Service`, `Manager`, `Handler`, factory, or interface without a concrete pressure it removes.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- User request, target files, project context if known, and current repository instructions.
+- Existing source, tests, schemas, templates, contracts, docs, and nearby local patterns for the affected boundary.
+- Current or expected data flow: input, validation, transformation, storage or external calls, and output.
+- Failure classes: user input, authorization, business rule, external system, transient fault, concurrency, partial failure, and recovery path.
+- Public contracts affected: API response, CLI output, config schema, database schema, event, queue, webhook, migration, docs example, or user-visible behavior.
+- Relevant command-intent contract entries for verification.
+
+<!-- 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.
+- Skill-selection has chosen one main implementation skill when applicable; this skill normally acts as an adjunct gate.
+- Missing product, domain, compatibility, security, or migration decisions are either safely inferable from repository evidence or routed through a clarification gate.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Add or adjust boundaries, types, DTOs, pure domain functions, adapters, mappers, result/error models, tests, and docs that are directly required by the changed behavior.
+- Structure the implementation at module scale when it lowers change cost, isolates external volatility, or makes failure and tests explicit.
+- Do not add vague layers named only `Service`, `Manager`, `Handler`, `Helper`, or `Factory` unless the responsibility and volatility hidden by that layer are named.
+- Do not split files solely because they are large.
+- Do not invent dependency installation, migration execution, external services, or command authority.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Print or internally prepare a risk block before editing. If the host or user-facing flow makes pre-edit output noisy, keep the block as working notes and include the relevant parts in the final report.
+
+   ```text
+   [Work risk]: surface change | local logic change | domain rule change | public contract change | external I/O change | operational risk change
+   [Project context]: prototype | staging | production | unknown
+   [Core boundary]: domain/API/I/O/contract being touched
+   [Data flow]: input -> validation -> transformation -> storage/call -> output
+   [Failure points]: expected failures and handling strategy
+   [Test contract]: tests or reproduction/verification commands to add, update, or run
+   [Structure change]: needed/not needed, with reason
+   ```
+
+2. Classify the highest applicable work risk.
+   - Surface change: keep edits narrow and avoid structure changes.
+   - Local logic change: keep cleanup within the module and add or update focused tests.
+   - Domain rule change: isolate rules from I/O and framework delivery; prefer pure functions or use-case boundaries.
+   - Public contract change: preserve compatibility when possible and pin schema, fixture, snapshot, or contract tests.
+   - External I/O change: isolate the adapter, timeout and retry behavior, partial failure, and provider response mapping.
+   - Operational risk change: treat security, money, audit, deletion, concurrency, and recovery as highest intensity.
+3. Decide whether structure is allowed. Require at least one real pressure:
+   - responsibility separation is necessary;
+   - tests are tied to external factors;
+   - public contracts and internal representation are mixed;
+   - error categories are implicit or wrong;
+   - domain rules are duplicated;
+   - change impact is too broad;
+   - provider, framework, filesystem, network, time, randomness, or environment volatility leaks into domain logic.
+4. Control abstraction.
+   - Create an interface, factory, strategy, mapper, adapter, or use case only when there are at least two implementations, external volatility to hide, tests need control, a public contract must stay stable, a high-change area needs isolation, or duplicated domain rules need one owner.
+   - Name the responsibility in domain words. If the best name is only `Service`, `Manager`, `Handler`, or `Helper`, the boundary is probably still unclear.
+5. Trace data flow end to end.
+   - Keep system boundaries behind DTOs, schemas, interfaces, or mappers.
+   - Convert external API, database, CLI, event, or UI payloads into internal types near the boundary.
+   - Keep domain data immutable when practical.
+   - Avoid spreading raw `any`, broad `unknown`, provider response shapes, request bodies, or ORM records through the domain core.
+6. Model expected failures explicitly.
+   - Use local Result, Option, typed error, status object, or existing project convention for expected failures.
+   - Separate user-facing messages from debugging detail.
+   - Do not swallow exceptions or convert all failures into generic false, null, or success-with-warning states.
+   - Classify failures as input, auth/permission, business rule, external system, transient, concurrency, or partial failure.
+7. Isolate external I/O and unstable inputs.
+   - Keep domain rules from directly calling network, database, filesystem, clock, random, UUID, process environment, or framework request objects.
+   - Inject time, randomness, UUID, environment, and external clients when tests or determinism need control.
+   - Guard duplicate execution, timeout-unknown state, concurrent updates, partial failure, and compensation failure in code or explicitly report why the risk is not relevant.
+8. Protect public contracts.
+   - Treat API response/status codes, CLI output/exit codes, config schemas, database schemas/migrations, event/queue/webhook payloads, and docs examples as more stable than implementation shape.
+   - When a contract changes, synchronize docs, fixtures, schema, migration, generated clients, and tests that encode that contract.
+9. Set the test contract before or during implementation.
+   - Test pure logic without I/O.
+   - Make time, randomness, and environment controllable.
+   - For bug fixes, include a failing reproduction or explain why one is impossible.
+   - Name tests after the guarantee, not the implementation detail.
+   - Avoid mock-only confidence, meaningless copied fixtures, and snapshot-heavy approval unless the snapshot is the real contract.
+10. Check observability, security, and performance for risky paths.
+    - Add structured logs or trace/request IDs for important state transitions when the project has logging conventions.
+    - Keep authentication and authorization separate from untrusted input parsing and business rules.
+    - Remove I/O from tight loops or name why it is bounded. Include cache invalidation or freshness strategy when adding cache behavior.
+11. Handle verification failure by classifying the cause before changing more code:
+    - real regression;
+    - existing failure;
+    - wrong contract test;
+    - environment, dependency, or flaky issue.
+    If the cause is unknown, do not claim completion.
+12. If you intentionally skip a rule, record the exception:
+
+    ```text
+    [Exception applied]: skipped rule and reason
+    [Risk]: possible consequence
+    [Compensation]: test, TODO, docs, or follow-up
+    ```
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- The highest work risk is named and the structure decision matches that risk.
+- Domain rules, public contracts, adapters, data flow, and error handling have clear owners when touched.
+- External I/O and unstable inputs are behind testable boundaries when relevant.
+- Concurrency, partial failure, idempotency, and recovery are handled or explicitly marked not relevant.
+- Tests or verification commands cover the behavior and contract actually changed.
+- Any exception to the structure-first rules is reported with risk and compensation.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `lint`
+- `build`
+- `test_related`
+- `test`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Choose the narrowest configured verification that covers the highest work risk. Use release or docs checks when public contracts, templates, package metadata, schemas, or docs examples change.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If the risk block exposes a missing product, security, migration, or compatibility decision, stop and ask or use the clarifying-question gate.
+- If structure pressure is weak, do the narrow implementation and report that structure was intentionally deferred.
+- If the implementation starts becoming a broad rewrite, stop and split the work into a smaller boundary-preserving step.
+- If tests require too many mocks, revisit the boundary instead of weakening assertions.
+- If a configured command fails, switch to `failure-triage` before claiming completion.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Work risk and project context
+- Core boundary and data flow
+- Structure decision and reason
+- Failure model, I/O boundary, concurrency, and partial-failure notes
+- Public contract impact
+- Tests added, updated, or intentionally not added
+- Command intents run
+- Exceptions applied, if any
+- Remaining structure risk

package/templates/default/locales/en/.mustflow/skills/template-install-surface-sync/SKILL.md

@@ -0,0 +1,131 @@
+---
+mustflow_doc: skill.template-install-surface-sync
+locale: en
+canonical: true
+revision: 1
+lifecycle: mustflow-owned
+authority: procedure
+name: template-install-surface-sync
+description: Apply this skill when mustflow template install surfaces, template manifests, skill profiles, locale source files, init or update behavior, managed file lists, package inclusion, template command contracts, or source-to-template workflow copies are created, changed, reviewed, or reported.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.template-install-surface-sync
+  command_intents:
+    - changes_status
+    - changes_diff_summary
+    - test_related
+    - docs_validate_fast
+    - test_release
+    - mustflow_check
+---
+
+# Template Install Surface Sync
+
+<!-- mustflow-section: purpose -->
+## Purpose
+
+Keep the source repository's mustflow workflow files, install templates, manifests, profiles, locale policy, init/update behavior, and package tests aligned without blindly copying surfaces that must intentionally differ.
+
+<!-- mustflow-section: use-when -->
+## Use When
+
+- A mustflow-owned file is added, removed, renamed, or materially changed and that file may be installed by the default template.
+- Template `creates`, `skill_profiles`, locale source files, install policy, conflict policy, managed targets, generated targets, or forbidden targets change.
+- `.mustflow/skills/*`, `.mustflow/skills/INDEX.md`, `.mustflow/skills/routes.toml`, `AGENTS.md`, `.mustflow/docs/agent-workflow.md`, template configs, or template command contracts are changed.
+- `mf init`, `mf update`, manifest locks, backup behavior, package inclusion, release tests, or docs examples depend on installed template files.
+
+<!-- mustflow-section: do-not-use-when -->
+## Do Not Use When
+
+- The task changes only a normal downstream project that consumes mustflow and does not modify the template source or install/update behavior.
+- The change affects a declared contract but no install template, profile, locale, init, update, or package surface; use `contract-sync-check`.
+- The task is only creating or editing a skill procedure; use `skill-authoring` first, then use this skill only if the skill is installed by a template.
+- The user explicitly requests a local experiment that should not be reflected in install templates.
+
+<!-- mustflow-section: required-inputs -->
+## Required Inputs
+
+- Changed-file list and the intended installed behavior.
+- Source repository file, canonical template copy, and any localized source files.
+- `templates/default/manifest.toml` entries: `creates`, `skill_profiles`, locale metadata, install policy, managed targets, generated targets, forbidden targets, and conflict policy.
+- Init/update source code, package inclusion metadata, release or install tests, docs examples, and manifest-lock behavior that mention the changed surface.
+- Intentional divergence rules between source and template copies.
+- Relevant command-intent entries for related tests, docs validation, release checks, and mustflow validation.
+
+<!-- mustflow-section: preconditions -->
+## Preconditions
+
+- The task matches the Use When conditions and does not match the Do Not Use When exclusions.
+- Canonical source locale and template locale policy are known.
+- Existing template manifest and nearby tests have been inspected before adding or removing installed files.
+- Command execution remains governed by `.mustflow/config/commands.toml`; this skill does not authorize raw commands.
+
+<!-- mustflow-section: allowed-edits -->
+## Allowed Edits
+
+- Update source workflow files, canonical template copies, route metadata, manifest `creates`, profile membership, locale metadata, install/update tests, docs examples, and package file lists that own the same installed surface.
+- Add explicit divergence notes in skill or docs text when source and template behavior must differ.
+- Do not blindly copy the source repository's real command contract into a default template.
+- Do not install specialist skills into every profile unless the trigger is broadly useful for that profile.
+- Do not update localized skill copies unless that locale intentionally maintains translated skill text and review is available.
+- Do not manually edit generated manifest locks or generated repository maps unless a configured intent owns the generated output.
+
+<!-- mustflow-section: procedure -->
+## Procedure
+
+1. Name the installed surface being changed: root instructions, workflow docs, skill body, skill index, route metadata, context file, config file, command contract, preference, template manifest, locale file, init/update behavior, package artifact, docs example, or release test.
+2. Classify each surface as must-match, intentionally-divergent, generated, package-only, docs-only, or not-installed.
+3. For must-match surfaces, update the source file and canonical template copy together. Examples include skill bodies, route metadata, skill index entries, managed workflow docs, and installable context or config defaults.
+4. For intentionally-divergent surfaces, preserve the divergence and document the reason in the procedure or final report. Source repository command contracts usually contain real maintainer commands, while template command contracts should remain placeholders, unknown, or manual-only until a downstream project configures them.
+5. Check `templates/default/manifest.toml`. Add new installable files to `creates`, remove deleted files, and place new skills only in profiles that would genuinely benefit from the route.
+6. Check locale policy. Use the source locale as canonical. Non-source template locales may fall back to source-locale skill text unless translated skill text is intentionally maintained and review is available.
+7. Check route alignment. `.mustflow/skills/INDEX.md` and `.mustflow/skills/routes.toml` must agree on route names, category, route type, priority intent, and expected verification intent names.
+8. Check install/update behavior. If new files, profile membership, conflict policy, or managed targets change, inspect init/update tests and package tests that assert installed output, manifest lock behavior, backups, or diff previews.
+9. Check package and release surfaces. Installed template files must be included in package output and covered by release-sensitive tests when the package includes templates.
+10. Check public docs and examples only when they list installed files, profiles, init/update behavior, or workflow expectations.
+11. Keep generated files generated. Refresh generated maps or package output only with configured intents, and report generated surfaces that are stale but outside the current allowed command set.
+12. Verify with related tests first, then release and docs checks when package, template, manifest, or docs surfaces changed.
+
+<!-- mustflow-section: postconditions -->
+## Postconditions
+
+- Source and template surfaces match where they should match and intentionally diverge where they should diverge.
+- Manifest `creates`, skill profiles, locale policy, install/update behavior, package inclusion, tests, and docs agree with the installed surface.
+- Any deferred locale, docs, package, or generated surface is named with risk.
+
+<!-- mustflow-section: verification -->
+## Verification
+
+Use configured oneshot command intents when available:
+
+- `changes_status`
+- `changes_diff_summary`
+- `test_related`
+- `docs_validate_fast`
+- `test_release`
+- `mustflow_check`
+
+Use broader configured tests when init, update, package inclusion, or release behavior is cross-cutting or no narrower related test covers the template surface.
+
+<!-- mustflow-section: failure-handling -->
+## Failure Handling
+
+- If `mustflow_check` reports route or manifest drift, fix the source/template metadata mismatch before changing unrelated files.
+- If template tests fail after adding a file, check `creates`, profile membership, package inclusion, locale metadata, and generated map freshness before changing behavior.
+- If source and template command contracts differ, do not normalize them unless the divergence is proven accidental.
+- If a skill seems useful but profile impact is unclear, keep it out of narrow profiles and report the profile decision.
+- If localized surfaces cannot be confidently updated, keep canonical source metadata accurate and mark translation review instead of guessing.
+
+<!-- mustflow-section: output-format -->
+## Output Format
+
+- Installed template surface changed
+- Must-match surfaces synchronized
+- Intentional divergences preserved
+- Manifest creates and profiles updated
+- Locale, init/update, package, docs, and tests checked
+- Command intents run
+- Skipped checks and reasons
+- Remaining template drift risk

package/templates/default/locales/en/AGENTS.md

@@ -2,7 +2,7 @@
 mustflow_doc: agents.root
 locale: en
 canonical: true
-revision: 13
+revision: 14
 lifecycle: user-editable
 authority: binding
 ---
@@ -20,13 +20,14 @@ mustflow-managed details are under `.mustflow/`.
 3. `.mustflow/config/mustflow.toml`
 4. `.mustflow/config/commands.toml`
 5. `.mustflow/config/preferences.toml` if present
-6. `.mustflow/skills/INDEX.md`
-7. `.mustflow/context/INDEX.md` only when the task needs project, product, domain,
+6. `.mustflow/config/technology.toml` if present
+7. `.mustflow/skills/INDEX.md`
+8. `.mustflow/context/INDEX.md` only when the task needs project, product, domain,
    UI, backend, data, security, or operations context
-8. The matching `.mustflow/context/<name>.md` files, only when selected by the context index
-9. The matching `.mustflow/skills/<name>/SKILL.md`
-10. `REPO_MAP.md` only when broader repository navigation is needed
-11. Relevant source, test, and documentation files
+9. The matching `.mustflow/context/<name>.md` files, only when selected by the context index
+10. The matching `.mustflow/skills/<name>/SKILL.md`
+11. `REPO_MAP.md` only when broader repository navigation is needed
+12. Relevant source, test, and documentation files
 
 ## Core Rules
 

package/templates/default/locales/ko/AGENTS.md

@@ -2,7 +2,7 @@
 mustflow_doc: agents.root
 locale: ko
 canonical: false
-revision: 20
+revision: 21
 lifecycle: user-editable
 authority: binding
 ---
@@ -20,13 +20,14 @@ mustflow가 관리하는 세부 문서와 설정은 `.mustflow/` 폴더 아래
 3. `.mustflow/config/mustflow.toml`  
 4. `.mustflow/config/commands.toml`  
 5. `.mustflow/config/preferences.toml` (있다면)  
-6. `.mustflow/skills/INDEX.md`  
-7. 프로젝트, 제품, 도메인, UI, 백엔드, 데이터, 보안, 운영 컨텍스트가 필요한 경우  
+6. `.mustflow/config/technology.toml` (있다면)  
+7. `.mustflow/skills/INDEX.md`  
+8. 프로젝트, 제품, 도메인, UI, 백엔드, 데이터, 보안, 운영 컨텍스트가 필요한 경우  
    `.mustflow/context/INDEX.md`  
-8. 컨텍스트 색인에서 선택된 `.mustflow/context/<name>.md` 파일  
-9. 현재 작업과 관련된 `.mustflow/skills/<name>/SKILL.md`  
-10. 넓은 저장소 탐색이 필요할 때만 `REPO_MAP.md`  
-11. 관련 소스, 테스트, 문서 파일
+9. 컨텍스트 색인에서 선택된 `.mustflow/context/<name>.md` 파일  
+10. 현재 작업과 관련된 `.mustflow/skills/<name>/SKILL.md`  
+11. 넓은 저장소 탐색이 필요할 때만 `REPO_MAP.md`  
+12. 관련 소스, 테스트, 문서 파일
 
 ## 핵심 규칙