mustflow 1.15.99 → 1.17.0

package/README.md

@@ -55,7 +55,7 @@ flowchart TD
 
 `read_order` defines the required reading sequence, while `optional_read_order` and `[context]` control how task-specific context loads. The `[refresh]` policy sets when agents reread the same instructions.
 
-The skills index acts as an active routing step: agents compare the task with `.mustflow/skills/INDEX.md` and read matching `SKILL.md` files before editing that scope. Skills guide procedure only; command execution still comes from `.mustflow/config/commands.toml`.
+The skills index acts as an active routing step: agents compare the task with `.mustflow/skills/INDEX.md` and read matching `SKILL.md` files before editing that scope. This step is required before file edits even when `mf doctor` or `mf check` passes, because health checks do not decide which task procedure applies. Skills guide procedure only; command execution still comes from `.mustflow/config/commands.toml`.
 
 ## Quick start
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mustflow",
-	"version": "1.15.99",
+	"version": "1.17.0",
   "description": "Agent workflow documents and CLI for mustflow repository roots.",
   "type": "module",
   "license": "MIT-0",

package/templates/default/i18n.toml

@@ -10,8 +10,8 @@ status_values = ["current", "stale", "needs_review", "missing"]
 [documents."agents.root"]
 source = "locales/en/AGENTS.md"
 source_locale = "en"
-revision = 11
-translations.ko = { path = "locales/ko/AGENTS.md", source_revision = 11, status = "current" }
+revision = 12
+translations.ko = { path = "locales/ko/AGENTS.md", source_revision = 12, status = "current" }
 translations.zh = { path = "locales/zh/AGENTS.md", source_revision = 11, status = "needs_review" }
 translations.es = { path = "locales/es/AGENTS.md", source_revision = 11, status = "needs_review" }
 translations.fr = { path = "locales/fr/AGENTS.md", source_revision = 11, status = "needs_review" }
@@ -76,7 +76,7 @@ translations.hi = { path = "locales/hi/.mustflow/skills/adapter-boundary/SKILL.m
 [documents."skill.artifact-integrity-check"]
 source = "locales/en/.mustflow/skills/artifact-integrity-check/SKILL.md"
 source_locale = "en"
-revision = 4
+revision = 5
 translations.ko = { path = "locales/ko/.mustflow/skills/artifact-integrity-check/SKILL.md", source_revision = 1, status = "needs_review" }
 translations.zh = { path = "locales/zh/.mustflow/skills/artifact-integrity-check/SKILL.md", source_revision = 1, status = "needs_review" }
 translations.es = { path = "locales/es/.mustflow/skills/artifact-integrity-check/SKILL.md", source_revision = 1, status = "needs_review" }

package/templates/default/locales/en/.mustflow/skills/artifact-integrity-check/SKILL.md

@@ -2,7 +2,7 @@
 mustflow_doc: skill.artifact-integrity-check
 locale: en
 canonical: true
-revision: 4
+revision: 5
 lifecycle: mustflow-owned
 authority: procedure
 name: artifact-integrity-check
@@ -50,6 +50,7 @@ Ensure generated artifacts, packaged files, media assets, reports, and downloada
 - Artifact paths or expected output locations.
 - Source files, generation steps, or package rules that should produce the artifact.
 - Any size, format, hash, manifest, package, or documentation expectation.
+- Declared version source, current published version, intended release tag, and SemVer decision when the artifact is versioned.
 - Relevant command-intent contract entries for build, packaging, validation, or asset optimization.
 - Workflow steps, action references, publish credentials, OIDC permissions, package registry identity, and pre-publish lifecycle scripts when artifacts are released.
 - Code-scanning artifact paths, upload steps, credential scope, and whether the uploaded artifact can contain checkout credentials, generated secrets, or tampered package contents.
@@ -76,12 +77,17 @@ Ensure generated artifacts, packaged files, media assets, reports, and downloada
 3. Check that source references, manifests, package includes, docs links, and tests point to the same path and format.
 4. For publish workflows, inspect code that runs before artifact publication. Treat mutable third-party actions, lifecycle scripts, package manifests, and generated files as artifact mutation points.
 5. Prefer explicit release gates for publish automation. Do not publish packages on every branch push; use a version tag or a manually published release, then verify the tag matches the package metadata before publication.
-6. If a workflow creates a release and publishes an artifact, keep release creation and publication in the same trusted workflow unless it uses a token that is intended to trigger follow-up workflows. Repository `GITHUB_TOKEN` events generally should not be used as the only trigger for a second publish workflow.
-7. For workflow artifact alerts, check whether checkout credentials persist into the workspace, whether artifacts are uploaded after untrusted code runs, and whether the job permission is broader than the artifact operation needs.
-8. Verify existence, format, and expected inclusion using the narrowest configured command intent available.
-9. If a generated artifact is stale or missing, regenerate it only through a configured command intent or report the missing command.
-10. If an artifact should not be versioned, ensure the final report does not imply that it was committed or distributed.
-11. Report artifact evidence precisely: path checked, command intent run, and any remaining unverified attribute.
+6. When changing a versioned artifact, choose the version bump from the declared repository versioning policy first. If no narrower policy is declared, use SemVer as follows:
+   - Increment `X` in `X.Y.Z` only for breaking changes to public commands, schemas, package entrypoints, installed template contracts, or documented behavior that existing users may rely on.
+   - Increment `Y` for backward-compatible new capabilities, newly installed skills or workflow guidance, new public commands, new schema fields that old consumers can ignore, or meaningful template behavior that users receive after installation or update.
+   - Increment `Z` for backward-compatible fixes, packaging corrections, documentation or prose repairs, test-only changes, internal refactors, or release automation fixes that do not add a user-facing capability.
+7. Do not bump a version just because files changed. Record the artifact surface that justifies the bump and keep every declared version source synchronized with the chosen version.
+8. If a workflow creates a release and publishes an artifact, keep release creation and publication in the same trusted workflow unless it uses a token that is intended to trigger follow-up workflows. Repository `GITHUB_TOKEN` events generally should not be used as the only trigger for a second publish workflow.
+9. For workflow artifact alerts, check whether checkout credentials persist into the workspace, whether artifacts are uploaded after untrusted code runs, and whether the job permission is broader than the artifact operation needs.
+10. Verify existence, format, and expected inclusion using the narrowest configured command intent available.
+11. If a generated artifact is stale or missing, regenerate it only through a configured command intent or report the missing command.
+12. If an artifact should not be versioned, ensure the final report does not imply that it was committed or distributed.
+13. Report artifact evidence precisely: path checked, command intent run, version bump reason when applicable, and any remaining unverified attribute.
 
 <!-- mustflow-section: postconditions -->
 ## Postconditions
@@ -89,6 +95,7 @@ Ensure generated artifacts, packaged files, media assets, reports, and downloada
 - Every artifact claim in code, docs, manifests, tests, and the final report is backed by observed evidence or explicitly marked unverified.
 - Generated and ignored outputs are not treated as project truth unless the repository declares them versioned.
 - Package or distribution claims are verified with the relevant configured intent when available.
+- Versioned artifact releases have a documented bump reason and synchronized version sources.
 
 <!-- mustflow-section: verification -->
 ## Verification
@@ -108,6 +115,7 @@ Use a narrower configured asset or documentation validation intent when it bette
 
 - If the artifact cannot be generated or inspected, report the missing tool, command intent, or source file.
 - If package inclusion and source references disagree, fix the manifest or docs before reporting the artifact as shipped.
+- If the intended version bump does not match the changed public surface, stop and correct the version or report why a project-specific policy overrides the default SemVer decision.
 - If a privileged release workflow runs mutable actions or repository-controlled code before publishing, report the artifact integrity risk or isolate and pin the publish path before claiming the package is trustworthy.
 - If an artifact is too large, stale, or in the wrong format, report the issue and avoid claiming it is production-ready.
 - If verification would require external services or unavailable tools, stop at that boundary and name the unchecked artifact property.
@@ -118,6 +126,7 @@ Use a narrower configured asset or documentation validation intent when it bette
 - Artifact paths checked
 - Artifact source or generation path
 - Inclusion, format, or size evidence
+- Version bump decision and synchronized version sources, when applicable
 - Command intents run
 - Skipped artifact checks and reasons
 - Remaining artifact integrity risk

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

@@ -2,7 +2,7 @@
 mustflow_doc: agents.root
 locale: en
 canonical: true
-revision: 11
+revision: 12
 lifecycle: user-editable
 authority: binding
 ---
@@ -63,7 +63,14 @@ mustflow-managed details are under `.mustflow/`.
 - If `DESIGN.md` exists, read it only for UI, visual design, layout, design-token, or accessibility
   work. Do not create a `DESIGN.md` if one does not exist.
 - Read the matching skill document when one applies to the task.
-- Before editing, use `.mustflow/skills/INDEX.md` to decide whether one or more skills apply.
+- Before creating or modifying any file, use `.mustflow/skills/INDEX.md` to decide whether one or more skills apply.
+  This skill-selection gate is mandatory even for small or seemingly obvious tasks.
+- `mf doctor`, `mf check`, and other health checks do not satisfy the skill-selection gate. They
+  confirm repository health; they do not decide which task procedure applies.
+- If a matching skill applies, read the matching `SKILL.md` before editing that scope. If no
+  installed skill matches, state that no matching installed skill was found in the next progress
+  update or final report. If a plausible skill is referenced by the index but is unavailable in
+  the installed profile, report that gap instead of silently continuing.
 - If a skill becomes relevant after new evidence, such as a command failure or a documentation
   change, read the matching `SKILL.md` before continuing that part of the work.
 - Skill documents guide procedure. They do not authorize commands outside

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

@@ -2,7 +2,7 @@
 mustflow_doc: agents.root
 locale: ko
 canonical: false
-revision: 17
+revision: 18
 lifecycle: user-editable
 authority: binding
 ---
@@ -46,7 +46,9 @@ mustflow가 관리하는 세부 문서와 설정은 `.mustflow/` 폴더 아래
 - `.mustflow/context/` 파일은 프로젝트 방향과 도메인 약속을 설명하는 작업별 문맥입니다. 코드, 테스트, 명령 계약, 사용자 지시를 대신하는 최종 기준으로 보지 않습니다.  
 - `DESIGN.md`가 있으면 UI, 시각 디자인, 레이아웃, 디자인 토큰, 접근성 작업에서만 읽습니다. 없는 `DESIGN.md`를 임의로 생성하지 않습니다.  
 - 작업과 맞는 스킬이 있으면 해당 `SKILL.md`를 읽고 따릅니다.  
-- 수정 전 `.mustflow/skills/INDEX.md`를 기준으로 현재 작업에 적용 가능한 스킬이 하나 이상 있는지 판단합니다.  
+- 파일을 만들거나 수정하기 전에 `.mustflow/skills/INDEX.md`를 기준으로 현재 작업에 적용 가능한 스킬이 하나 이상 있는지 판단합니다. 이 스킬 선택 단계는 작업이 작거나 명백해 보이는 경우에도 반드시 거쳐야 합니다.
+- `mf doctor`, `mf check` 같은 상태 점검 명령은 스킬 선택 단계를 대신하지 않습니다. 이 명령들은 저장소 상태를 확인할 뿐, 현재 작업에 어떤 절차가 필요한지 결정하지 않습니다.
+- 적용되는 스킬이 있으면 해당 범위를 편집하기 전에 맞는 `SKILL.md`를 읽습니다. 설치된 스킬 중 맞는 항목이 없으면 다음 진행 보고나 최종 보고에서 “일치하는 설치 스킬이 없음”을 밝힙니다. 색인에는 그럴듯한 스킬이 보이지만 현재 프로필에 설치되어 있지 않다면, 조용히 넘어가지 말고 그 누락을 보고합니다.
 - 명령 실패나 문서 변경 등 작업 중 새 근거가 생겨 스킬이 필요해지면, 해당 범위를 계속하기 전에 반드시 맞는 `SKILL.md`를 읽습니다.  
 - 스킬 문서는 절차 안내용일 뿐 `.mustflow/config/commands.toml` 밖의 명령 실행을 허용하거나 사용자, 호스트, 저장소, 안전 규칙을 덮어쓰지 않습니다.  
 - 생성 파일, 외부 의존성, 비밀 정보 파일은 명시적 요청 없이는 수정하지 않습니다.  

package/templates/default/manifest.toml

@@ -1,6 +1,6 @@
 id = "default"
 name = "default"
-version = "1.15.99"
+version = "1.17.0"
 description = "Minimal workflow for LLM agents to read, edit, and verify their work in a repository."
 common_root = "common"
 locales_root = "locales"