mustflow 1.15.97

package/templates/default/locales/ko/.mustflow/skills/web-asset-optimization/SKILL.md

@@ -0,0 +1,108 @@
+---
+mustflow_doc: skill.web-asset-optimization
+locale: ko
+canonical: false
+revision: 2
+lifecycle: mustflow-owned
+authority: procedure
+name: web-asset-optimization
+description: 웹사이트나 웹 앱에 쓰는 래스터 이미지 자산을 추가, 변환, 크기 조정, 교체 또는 검토할 때 적용합니다.
+metadata:
+  mustflow_schema: "1"
+  mustflow_kind: procedure
+  pack_id: mustflow.core
+  skill_id: mustflow.core.web-asset-optimization
+  command_intents:
+    - asset_optimize
+    - build
+---
+
+# 웹 이미지 자산 최적화
+
+<!-- mustflow-section: purpose -->
+## 목적
+
+프로젝트에 없는 이미지 처리 파이프라인을 임의로 만들지 않으면서, 웹 이미지 자산을 작고 알맞은 형식으로 유지하고 참조 경로까지 정확히 맞춥니다.
+
+<!-- mustflow-section: use-when -->
+## 사용 조건
+
+- 생성된 PNG, JPEG, WebP, AVIF, GIF 같은 래스터 이미지가 웹사이트나 웹 앱에 추가될 때.
+- 기존 웹 이미지를 교체, 크기 조정, 압축 또는 형식 변환할 때.
+- 페이지, 컴포넌트, 스타일시트, 메타데이터 파일의 이미지 참조가 바뀔 때.
+- 사용자가 이미지 용량 축소, WebP 또는 AVIF 변환, 생성 이미지의 배포 준비를 요청할 때.
+
+<!-- mustflow-section: do-not-use-when -->
+## 사용하지 않는 경우
+
+- 대상이 SVG, 아이콘 폰트, 디자인 토큰 파일 같은 벡터 원본일 때.
+- 원본 바이트 보존이 웹 전송 용량보다 중요한 보관용, 인쇄용, 증거용 자산일 때.
+- 저장소에 더 구체적인 미디어, 디자인 시스템, 프레임워크 자산 절차가 이미 있을 때.
+- 새 이미지를 생성만 하고 저장소에 설치하거나 참조하지 않는 작업일 때.
+
+<!-- mustflow-section: required-inputs -->
+## 필요한 입력
+
+- 이미지 파일 경로와 현재 또는 예정된 참조 위치.
+- 예상 표시 크기, 투명도 필요 여부, 애니메이션 필요 여부, 품질 요구 사항.
+- 기존 프레임워크 이미지 규칙, 정적 자산 폴더, 가져오기 방식.
+- `.mustflow/config/commands.toml`의 `asset_optimize` 및 `build` 의도.
+
+<!-- mustflow-section: preconditions -->
+## 사전 조건
+
+- 작업이 사용 조건에 맞고 사용하지 않는 경우에는 해당하지 않습니다.
+- 필요한 입력을 확보했거나, 빠진 입력을 추측하지 않고 보고할 수 있습니다.
+- 현재 범위에 대해 더 높은 우선순위의 지침과 `.mustflow/config/commands.toml`을 확인했습니다.
+
+<!-- mustflow-section: allowed-edits -->
+## 허용 수정 범위
+
+- 이 스킬, 사용자 요청, `.mustflow/skills/INDEX.md`의 맞는 경로가 설명하는 범위 안에서만 수정합니다.
+- 명령 권한을 넓히거나, 프로젝트 사실을 지어내거나, 관련 없는 워크플로 파일을 변경하지 않습니다.
+
+<!-- mustflow-section: procedure -->
+## 절차
+
+1. 변경된 이미지 자산과 그 자산을 참조하는 페이지, 컴포넌트, 스타일, 메타데이터, 매니페스트를 모두 확인합니다.
+2. 자산을 바꾸기 전에 원본 파일 크기, 이미지 크기, 형식, 투명도, 애니메이션 여부를 확인합니다.
+3. 기존 이미지 파이프라인, 프레임워크 이미지 컴포넌트, 설정된 `asset_optimize` 의도가 있으면 그것을 우선 사용합니다.
+4. 사용자가 명시적으로 승인했거나 저장소가 이미 쓰고 있는 경우가 아니라면 새 의존성, 온라인 서비스, 임의 변환 도구를 추가하지 않습니다.
+5. 실제 필요에 맞춰 출력 형식을 고릅니다. 대부분의 사진형 또는 생성형 비트맵 웹 자산은 WebP 또는 AVIF를 우선 검토하고, 무손실 투명도나 정확한 픽셀이 중요하면 PNG를 유지하며, 실제 벡터 아트워크에만 SVG를 사용합니다.
+6. 저장소에 원본과 파생 자산을 분리하는 규칙이 있으면 따릅니다. 그런 규칙이 없다면 이후 편집에 꼭 필요한 경우가 아니면 중복 원본을 추가하지 않습니다.
+7. 지역 스타일에 맞춰 가져오기 구문, 정적 경로, 메타데이터 참조, 치수, 캐시에 민감한 파일 이름을 갱신합니다.
+8. 변경 전후 파일 크기를 비교하고, 품질, 투명도, 애니메이션, 브라우저 지원, 대체 형식 관련 위험을 기록합니다.
+
+<!-- mustflow-section: postconditions -->
+## 사후 조건
+
+- 명확한 근거, 실행한 명령 의도, 건너뛴 확인, 남은 위험을 포함해 예상 출력을 작성할 수 있습니다.
+- 빠진 명령 의도, 알 수 없는 입력, 권한 충돌은 숨기지 않고 보고합니다.
+
+<!-- mustflow-section: verification -->
+## 검증
+
+가능한 경우 설정된 일회성 명령 의도를 사용합니다.
+
+- `asset_optimize`
+- `build`
+
+이미지 최적화 명령을 추측하지 마십시오. `asset_optimize`가 unknown, missing, manual-only 상태이거나 에이전트 실행 가능 상태가 아니라면, 그 상태를 보고하고 설정되지 않은 도구를 실행하지 않은 채 의도한 최적화 내용을 설명합니다.
+
+<!-- mustflow-section: failure-handling -->
+## 실패 대응
+
+- 최적화 결과가 눈에 띄게 나빠지거나 투명도가 깨지면 더 나은 자산을 복구하거나 유지하고 그 절충점을 보고합니다.
+- 이미지 참조가 깨지면 해당 참조를 소유한 가장 가까운 가져오기 구문, 경로, 메타데이터, 빌드 설정을 수정합니다.
+- 저장소에 최적화 명령이 없으면 외부 웹사이트나 추측한 패키지 명령을 실행하지 말고, 가장 작은 프로젝트별 명령 의도 추가안을 제안합니다.
+- 자산 변경 뒤 빌드가 실패하면 관련 없는 코드를 만지기 전에 이미지 자산과 관련된 첫 실패를 조사합니다.
+
+<!-- mustflow-section: output-format -->
+## 출력 형식
+
+- 검토하거나 변경한 이미지
+- 형식 및 용량 변경
+- 갱신한 참조
+- 실행한 명령 의도
+- 건너뛴 명령 의도와 이유
+- 남은 이미지 품질 또는 브라우저 지원 위험

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

@@ -0,0 +1,85 @@
+---
+mustflow_doc: agents.root
+locale: ko
+canonical: false
+revision: 17
+lifecycle: user-editable
+authority: binding
+---
+
+# AGENTS.md
+
+이 파일은 LLM 코딩 에이전트가 이 저장소에서 가장 먼저 읽어야 할 작업 규칙입니다.  
+이 저장소는 mustflow 에이전트 작업 흐름 구조를 따릅니다.  
+mustflow가 관리하는 세부 문서와 설정은 `.mustflow/` 폴더 아래에 위치합니다.
+
+## 읽는 순서
+
+1. `AGENTS.md`  
+2. `.mustflow/docs/agent-workflow.md`  
+3. `.mustflow/config/mustflow.toml`  
+4. `.mustflow/config/commands.toml`  
+5. `.mustflow/config/preferences.toml` (있다면)  
+6. `.mustflow/skills/INDEX.md`  
+7. 프로젝트, 제품, 도메인, UI, 백엔드, 데이터, 보안, 운영 문맥이 필요한 경우  
+   `.mustflow/context/INDEX.md`  
+8. 문맥 색인에서 선택된 `.mustflow/context/<name>.md` 파일  
+9. 현재 작업과 관련된 `.mustflow/skills/<name>/SKILL.md`  
+10. 넓은 저장소 탐색이 필요할 때만 `REPO_MAP.md`  
+11. 관련 소스, 테스트, 문서 파일
+
+## 핵심 규칙
+
+- 기존 변경 사항은 되돌리지 않습니다.  
+- 명령어를 임의로 추측하지 않습니다.  
+- `status = "configured"`, `lifecycle = "oneshot"`, `run_policy = "agent_allowed"`인 명령 의도만 실행합니다.  
+- 단발성 명령은 가능하면 `mf run <intent>`로 실행하며, 자동화나 최종 보고 근거가 필요할 경우 `mf run <intent> --json` 실행 결과를 기록으로 사용합니다.  
+- `mf run` 명령 의도는 순차적으로 실행합니다. 설정된 의도가 아직 실행 중이면 다른 `mf run`을 시작하지 말고, 특히 의도가 `dist/`처럼 비어 있지 않은 `writes`를 선언한 경우 반드시 완료될 때까지 기다립니다.  
+- 위험을 최소화하는 가장 좁은 검증 의도를 선택합니다. 명령 계약에 관련 테스트나 빠른 검사가 있으면 넓은 전체 테스트보다 우선하며, 더 좁은 검증 의도가 없으면 느린 전체 테스트를 조용히 기본값으로 삼지 말고 누락 사실을 보고합니다.  
+- 개발 서버, 감시 모드, 브라우저, 대화형 명령, 백그라운드 프로세스는 직접 실행하지 않습니다.  
+- 이 저장소가 명시적으로 설정하지 않았다면 자율 반복 실행기, 다중 작업자 조정, 페르소나 시스템, 장기 실행 하네스는 시작하지 않습니다.  
+- 작업이 장시간 실행되거나 민감한 상태에 영향을 줄 수 있다면 `.mustflow/config/mustflow.toml`의 `[budget]`, `[approval]`, `[isolation]` 정책을 따릅니다.  
+- 수정 전 현재 mustflow 루트 상태와 다음 단계를 빠르게 확인하려면 `mf doctor` 또는 `mf doctor --json`을 사용합니다. 이 명령은 파일을 쓰지 않는 진단용 명령입니다.  
+- `mf context --json`은 읽기 전용 문맥 확인 용도로 사용할 수 있으나, 실제 작업 규칙이나 명령 계약을 대체하지 않습니다.  
+- `.mustflow/config/preferences.toml`의 선호값은 사용자 직접 지시와 기존 파일 스타일보다 낮은 기본값으로 취급합니다.  
+- 코드, 템플릿, 스키마, CLI 동작, 패키지 메타데이터, 사용자에게 보이는 문서, 설치 출력, 테스트가 변경되면 최종 보고 전에 `.mustflow/config/preferences.toml`의 `[release.versioning]`을 확인합니다. 버전 파일은 해당 선호값에 따라서만 변경할 수 있습니다. `auto_bump = true`이고 `require_user_confirmation = false`이면 자동으로 버전 판올림을 적용하며, 그렇지 않으면 설정에 따라 판올림을 제안하거나 수정 전에 사용자 확인을 받습니다. 버전 기준 파일이 `package.json`이라고 가정하지 말고, 제안하거나 수정하기 전에 이 저장소에서 실제 기준으로 사용하는 버전 위치를 반드시 확인합니다.  
+- `.mustflow/context/` 파일은 프로젝트 방향과 도메인 약속을 설명하는 작업별 문맥입니다. 코드, 테스트, 명령 계약, 사용자 지시를 대신하는 최종 기준으로 보지 않습니다.  
+- `DESIGN.md`가 있으면 UI, 시각 디자인, 레이아웃, 디자인 토큰, 접근성 작업에서만 읽습니다. 없는 `DESIGN.md`를 임의로 생성하지 않습니다.  
+- 작업과 맞는 스킬이 있으면 해당 `SKILL.md`를 읽고 따릅니다.  
+- 수정 전 `.mustflow/skills/INDEX.md`를 기준으로 현재 작업에 적용 가능한 스킬이 하나 이상 있는지 판단합니다.  
+- 명령 실패나 문서 변경 등 작업 중 새 근거가 생겨 스킬이 필요해지면, 해당 범위를 계속하기 전에 반드시 맞는 `SKILL.md`를 읽습니다.  
+- 스킬 문서는 절차 안내용일 뿐 `.mustflow/config/commands.toml` 밖의 명령 실행을 허용하거나 사용자, 호스트, 저장소, 안전 규칙을 덮어쓰지 않습니다.  
+- 생성 파일, 외부 의존성, 비밀 정보 파일은 명시적 요청 없이는 수정하지 않습니다.  
+- 루트의 `config/`, `docs/`, `skills/`는 프로젝트 자체 경로일 수 있으므로 mustflow 문서로 간주하지 않습니다.
+
+## 상위/하위 규칙 우선순위
+
+- 현재 작업 경로에 더 가까운 `AGENTS.md`가 더 구체적인 규칙입니다.  
+- 작업 방식, 코드 스타일, 테스트 방식, 명령 실행 규칙이 충돌할 경우 하위 저장소의 `AGENTS.md`와 `.mustflow/config/commands.toml`을 우선합니다.  
+- 보안, 비밀 정보, 개인정보, 파괴적 명령, 수정 가능 경로 등 안전 규칙은 누적 적용하며 더 엄격한 규칙을 따릅니다.  
+- 상위 작업 공간에서 하위 저장소로 진입한 경우, 하위 저장소의 `AGENTS.md`와 `.mustflow/config/*.toml`을 다시 읽은 뒤 작업합니다.  
+- 명시적 요청 없이 선택한 하위 저장소 밖의 파일은 수정하지 않습니다.
+
+## 호스트별 지침 호환성
+
+일부 코딩 호스트는 자체 지침 파일을 읽거나 승인, 샌드박스, 체크포인트, 명령 실행 정책을 별도로 적용할 수 있습니다.
+
+이러한 호스트 정책은 추가 안전 제약과 실행 제한으로 간주하며, 이 저장소의 mustflow 명령 계약을 대체하지 않습니다. 호스트 지침과 mustflow 규칙이 충돌할 경우 다음 기준을 따릅니다.
+
+- 현재 사용자 직접 지시는 안전하지 않은 경우가 아니라면 작업 목표를 결정합니다.  
+- 호스트의 안전 규칙과 승인 절차는 계속 유효합니다.  
+- 저장소 작업 규칙은 가장 가까운 `AGENTS.md`와 `.mustflow/config/*.toml`에서 가져옵니다.  
+- 프로젝트 검증 명령은 설정된 mustflow 명령 의도를 사용해야 합니다.  
+- 개인정보, 비밀 정보, 파괴적 명령, Git 푸시 규칙은 더 엄격한 쪽을 따릅니다.  
+- 생성된 상태, 요약, 캐시는 현재 파일이나 현재 사용자 지시보다 우선하지 않습니다.
+
+유효 규칙이 불명확하면 추측하지 말고 작업을 멈춘 뒤 충돌 내용을 보고합니다.
+
+## 지침 새로고침 지점
+
+- 긴 세션에서는 첫 수정 전, 현재 명령 의도에 대한 신선한 명령 확인이 없을 때의 명령 실행 전, 문맥 압축 후, `AGENTS.md` 또는 `.mustflow/**` 수정 후, 루트 변경 후, 최종 보고 전에 mustflow 지침을 다시 확인합니다.  
+- `.mustflow/config/mustflow.toml`의 `[refresh]` 정책을 기준으로 가벼운 확인, 명령 확인, 스킬 확인, 전체 확인 중 필요한 수준을 판단합니다.  
+- 대화 횟수나 세션 활동 상태를 프로젝트 파일에 저장하지 않습니다. 세션 새로고침 상태는 로컬 캐시나 호스트 애플리케이션이 관리합니다.
+
+세부 작업 흐름, 명령 실행 정책, 실패 대응, 보안 원칙은  
+`.mustflow/docs/agent-workflow.md`를 따릅니다.

package/templates/default/locales/zh/.mustflow/context/INDEX.md

@@ -0,0 +1,39 @@
+---
+mustflow_doc: context.index
+kind: mustflow-context
+locale: zh
+canonical: false
+revision: 1
+lifecycle: mustflow-owned
+name: context-index
+authority: router
+stability: medium
+review_status: needs_human_review
+---
+
+# 上下文索引
+
+请根据本文件判断当前任务应读取哪些项目上下文文件。  
+默认情况下不建议读取全部上下文文件，以减少干扰信息。
+
+## 可用上下文
+
+| 上下文   | 使用时机                                         | 路径                     |
+| -------- | ------------------------------------------------ | ------------------------ |
+| project  | 任务可能影响项目方向、范围、对外行为、non-goals 或仓库级约定时。 | `.mustflow/context/PROJECT.md` |
+
+## 可选外部参考
+
+| 锚点           | 使用时机                                               | 路径          |
+| -------------- | ------------------------------------------------------ | ------------- |
+| human overview | 需要公开项目概览或安装指南时。应将其视为一般上下文，而非强制策略。 | `README.md`   |
+| roadmap        | 需要项目计划、优先级、里程碑或 non-goals 上下文时。应将其视为计划上下文，而非 mustflow 已安装的策略。 | `ROADMAP.md`  |
+| visual design  | 任务涉及 UI、视觉识别、design token、布局或可访问性变更时。 | `DESIGN.md`   |
+
+## 阅读规则
+
+- 仅阅读与当前任务相关的上下文文件。  
+- 除非有更高权威来源明确支持，否则将上下文文件视为参考指导。  
+- 若上下文与代码、测试、命令规范或用户明确指令冲突，应报告冲突并遵循更高权威来源。  
+- 不得假设或编造缺失的项目目标、non-goals、design token、API 合约或数据规则。  
+- 不得将 `DESIGN.md` 中的 design token 复制到 `.mustflow/context/` 目录。

package/templates/default/locales/zh/.mustflow/context/PROJECT.md

@@ -0,0 +1,64 @@
+---
+mustflow_doc: context.project
+kind: mustflow-context
+locale: zh
+canonical: false
+revision: 1
+lifecycle: user-editable
+name: project
+authority: contextual
+stability: medium
+review_status: needs_human_review
+source_refs:
+  - AGENTS.md
+  - .mustflow/config/mustflow.toml
+  - .mustflow/config/commands.toml
+---
+
+# 项目上下文
+
+本文件用于记录面向编码代理的项目特定上下文。  
+若某字段信息未知，请保持未设置，切勿臆测或填充无依据的内容。
+
+## 权限边界
+
+- 本文件可用于记录有据可依的上下文信息、未确定事项及冲突。  
+- 本文件不得赋予命令执行权限、设定文件编辑禁令、覆盖 `AGENTS.md` 或  
+  `.mustflow/config/*.toml` 文件，也不得承诺当前来源未支持的功能。  
+- 持久的操作规则应集中管理于 `AGENTS.md`、`.mustflow/docs/agent-workflow.md` 或相应配置文件，而非存放于此。
+
+## 当前目标
+
+未设置。待项目负责人明确后，将用实际项目目标替换此处内容。
+
+## 非目标（Non-Goals）
+
+未设置。请明确代理在非相关任务中不应涉及的范围或目标。
+
+## 核心承诺
+
+- 严格遵守 `AGENTS.md` 中的强制操作规则。  
+- 将 `.mustflow/config/commands.toml` 视为命令的唯一权威来源。  
+- 将 `.mustflow/config/mustflow.toml` 视为工作流与文档边界的唯一权威来源。  
+- 需要更广泛的仓库视图时，使用 `REPO_MAP.md` 作为浅层导航地图。
+
+## 领域术语
+
+未设置。仅添加对实现决策有影响的专用术语。
+
+## 重点关注区域
+
+未设置。请列出需特别关注的路径、公开 API、生成文件、迁移、密钥或兼容性相关部分。
+
+## 下一步阅读
+
+- `AGENTS.md`  
+- `.mustflow/docs/agent-workflow.md`  
+- `.mustflow/config/mustflow.toml`  
+- `.mustflow/config/commands.toml`  
+- `.mustflow/skills/INDEX.md`
+
+## 过期检查
+
+- 若本文件内容与当前代码、测试、命令合同或用户指令存在冲突，应视为过期并报告该冲突。  
+- 仅当项目方向、非目标或仓库范围承诺发生实质性变化时，方可更新本文件。

package/templates/default/locales/zh/.mustflow/docs/agent-workflow.md

@@ -0,0 +1,310 @@
+---
+mustflow_doc: docs.agent-workflow
+locale: zh
+canonical: false
+revision: 13
+lifecycle: mustflow-owned
+authority: workflow-policy
+---
+
+# 代理工作流
+
+本文档是对 `AGENTS.md` 中简要路由说明的扩展，定义了代理在 mustflow 根目录内的默认操作循环。
+
+## 方向校准
+
+开始编辑前，请先阅读 `AGENTS.md` 中列出的文件。可使用 `mf doctor` 进行快速只读健康检查，确认安装状态、已配置的命令意图及建议的下一步操作。
+
+请仅将 `REPO_MAP.md` 作为当前 mustflow 根目录的生成式导航图。它并非完整文件清单，不能替代对任务相关文件的实际阅读。
+
+## 项目上下文
+
+`.mustflow/context/` 包含面向代理的任务特定项目上下文，不是通用文档归档。
+
+- 仅当任务涉及项目、产品、领域、UI、后端、数据、安全或运维上下文时，才读取 `.mustflow/context/INDEX.md`。
+- 只读取索引中选定的上下文文件。
+- 将上下文文件视为辅助信息，优先级低于用户直接指令、当前代码、测试、命令合同和已配置策略。
+- 不要推断缺失的项目目标、非目标、API 承诺、数据规则或设计标记。
+- 若存在 `DESIGN.md`，在 UI 工作中将其视为可选的外部视觉设计参考，不要将其中的设计标记复制到 `.mustflow/context/`。
+- 若上下文与当前文件或命令冲突，应报告冲突并遵循更高权威来源。
+
+## Skill 激活
+
+Skill 是任务流程文档，不是自治工具。激活 skill 表示读取对应的 `.mustflow/skills/<name>/SKILL.md`，并在当前命令合同内遵循其流程。
+
+在任务开始和首次编辑前：
+
+1. 读取 `.mustflow/skills/INDEX.md`。
+2. 将当前任务与其中列出的场景进行匹配。
+3. 在编辑对应范围前，读取所有匹配的 `SKILL.md`。
+4. 若无适用 skill，不要臆造；在 `AGENTS.md` 和 `.mustflow/config/commands.toml` 下执行最小且安全的变更。
+
+若新证据改变任务类型，应在后续激活相应 skill。例如，已配置命令失败时激活 failure triage，测试合同变化时激活 test maintenance，文档或工作流变化时激活 docs update。
+
+当多个 skill 适用时，对每个受影响范围遵循最具体的 skill，并仅合并其声明的命令意图。skill 永远不会授权执行原始 shell 命令、长时运行进程或任务范围外写入。
+
+使用技能时，或有意跳过看似适用的技能时，请在下一次面向用户的更新或最终报告中简要说明技能名称和选择原因。不要仅为记录技能选择而创建纳入版本管理的工作日志。
+
+## 输入稳定性
+
+请将用户指令、本地文件、命令合同与生成报告视为独立信息源，避免混淆。
+
+- 用户直接指令优先。
+- 距离变更文件最近的 `AGENTS.md` 优先于更上层的广义规则。
+- `.mustflow/config/preferences.toml` 提供默认值，不是强制要求。
+- `REPO_MAP.md`、`.mustflow/cache/**` 与 `.mustflow/state/**` 等生成文件可能已过期。
+- compacted summary 属于状态的衍生表示，当前代码、配置、命令记录与当前用户指令优先于它们。
+
+当生成文件疑似过期时，应通过对应 `mf` 命令刷新，而非手工编辑。
+
+## 有效规则通道
+
+不要将所有指令混合成单一优先级表，应按规则类型解决冲突：
+
+- 用户目标：当前用户直接指令定义任务，除非该指令不安全。
+- 宿主安全：宿主的审批、沙箱和执行门禁更严格时仍然有效。
+- 仓库工作规则：使用最近的 `AGENTS.md` 和 `.mustflow/config/*.toml`。
+- 命令执行：`.mustflow/config/commands.toml` 是项目命令合同。
+- 验证证据：`mf run` 回执和当前文件比宿主 shell 直接输出更可信。
+- 上下文和偏好：`.mustflow/context/*`、`preferences.toml` 和生成地图是较低权威的默认值。
+- 会话和缓存状态：宿主摘要、`.mustflow/cache/**` 和 `.mustflow/state/**` 永远不能覆盖当前文件或当前用户指令。
+
+允许集合按交集收窄。禁止行为、审批要求、隐私规则和破坏性命令规则会累加。
+
+若有效规则不明确，应停止并报告冲突，而非猜测。
+
+## 指令刷新
+
+长会话可能导致指令漂移。应将指令刷新视为强制检查点，而非项目文件计数器。
+
+请在以下时机刷新 mustflow 指令：
+
+- 会话开始
+- 新任务开始
+- 第一次编辑前
+- 执行命令前（仅当当前任务和命令意图尚无新鲜的命令级刷新时）
+- 编辑 `AGENTS.md` 或 `.mustflow/**` 后
+- 切换根目录或进入嵌套仓库后
+- 上下文压缩或摘要后
+- 最终报告前
+- 达到配置的轮次、工具调用数或输出体量阈值后
+
+使用 `.mustflow/config/mustflow.toml` 的 `[refresh]` 配置决定刷新级别：
+
+- `light`：重读 `AGENTS.md` 与 `.mustflow/docs/agent-workflow.md`
+- `command`：重读 `AGENTS.md` 与 `.mustflow/config/commands.toml`
+- `skill`：重读 `AGENTS.md` 与 `.mustflow/skills/INDEX.md`
+- `full`：重读 mustflow 全部阅读序列
+
+`before_command_run` 是当前命令意图的新鲜度检查点；当命令合同无变化时，不要求每次执行命令前都重读所有文件。
+
+不要将轮次计数、消息计数或会话活动写入仓库。若代理宿主需跟踪刷新状态，应使用本地缓存或宿主管理状态，且放置于项目版本化文档之外。skills 可描述刷新行为，但不作为可靠的生命周期钩子。
+
+## 上下文压缩
+
+`compaction` 不是默认数据收集功能，而是未来 harness 或宿主应遵守的安全策略。默认模板保持禁用，仅声明安全规则。
+
+不要在项目中存储隐藏推理、密钥、完整聊天记录、完整终端输出、原始事件或原始命令日志。若未来宿主生成摘要，摘要必须带来源链接，且权威性低于当前文件和当前用户指令。
+
+## Harness 合同边界
+
+mustflow 不是自治代理运行时，而是面向代理 harness 的仓库本地合同层。
+
+- Brain contract：`AGENTS.md`、本工作流文件与 skill 文档定义模型预期行为。
+- Hands contract：`.mustflow/config/commands.toml` 与 `mf run` 定义安全命令执行。
+- Session contract：运行记录、边界检查点与紧凑交接为恢复提供证据。
+
+除非仓库明确引入，否则不要创建 worker 目录、persona 系统、fleet orchestration、原始事件日志或自治循环。
+
+## 长时任务阶段
+
+对于长时或恢复型任务，应区分以下阶段：
+
+1. Plan：阅读任务目标、仓库规则、命令合同与验收标准。
+2. Work：在当前单元上做最小且安全的修改。
+3. Verify：仅运行已配置的 oneshot command intents，优先通过 `mf run`。
+4. Judge：对照原始验收标准与运行回执评估结果。
+5. Handoff：当任务未完成、受阻或需续接时，留下紧凑交接信息。
+
+Judge 阶段不得仅凭 worker 的“完成声明”判定通过，应依据任务目标、变更文件、命令合同与运行回执。
+
+## Git 行为策略
+
+默认拒绝修改 Git 状态或历史的操作。
+
+- `git.auto_stage = false`：无用户请求时不暂存文件。
+- `git.auto_commit = false`：无用户请求时不创建提交。
+- `git.auto_push = false`：无用户请求时不推送。
+
+这些值是仓库偏好设置，不是权限控制。它们不会覆盖用户直接指令、`.mustflow/config/commands.toml`，也不会覆盖 `.mustflow/config/mustflow.toml` 中的审批策略。尤其是，`git.auto_commit = true` 不代表获得推送权限，且不能通过 `mf init` 启用 `git.auto_push = true`。
+
+## 版本影响策略
+
+版本影响设置是仓库偏好，指导版本文件编辑，但不会覆盖用户直接指令、宿主安全规则，也不会覆盖 `.mustflow/config/mustflow.toml` 中的审批关卡。
+
+当代码、模板、schema、CLI 行为、包元数据、用户可见文档、安装输出或测试发生变化时，使用 `.mustflow/config/preferences.toml` 中的 `[release.versioning]` 配置：
+
+- `impact_check = true`：报告当前差异是否可能需要包版本或模板版本变更。
+- `suggest_bump = true`：证据明确时，可建议 patch、minor 或 major 版本升级。
+- `auto_bump = true`：当影响明确、已定位版本来源，且无更严格的用户、宿主或审批规则阻止时，自动应用合适的版本升级。
+- `auto_bump = false`：除非用户请求版本升级或 release 准备任务，否则保持包和模板版本文件不变。
+- `require_user_confirmation = true`：编辑版本文件前先询问用户。
+- `require_user_confirmation = false`：当 `auto_bump = true` 时，不额外增加确认步骤。
+
+在建议或应用版本变更前，先定位仓库的版本事实来源。不要假设 `package.json` 是唯一版本文件，应检查与仓库语言和框架相匹配的 manifest、release 文档和既有更新模式，并报告哪些文件是权威来源，哪些是派生文件。
+
+常见版本来源候选包括：
+
+- JavaScript 或 TypeScript：`package.json` 及重复包元数据的包管理器 lockfile。
+- Python：`pyproject.toml`、`setup.cfg`、`setup.py` 或包内 `__version__` 文件。
+- Rust：`Cargo.toml`；仅当仓库将 lockfile 变更视为 release 元数据时才考虑 `Cargo.lock`。
+- Go：优先检查 release tag 和 release 文档；仅在模块路径或工具元数据相关时检查 `go.mod`。
+- Java 或 Kotlin：`pom.xml`、`build.gradle`、`build.gradle.kts` 或 `gradle.properties`。
+- .NET：`*.csproj`、`Directory.Build.props` 或 `*.nuspec`。
+- Ruby、PHP、Dart 或 Swift：`*.gemspec`、`lib/**/version.rb`、`composer.json`、`pubspec.yaml` 或 `Package.swift`。
+- 容器、chart 或应用：`Chart.yaml`、镜像标签、应用 manifest、release notes 或部署元数据。
+- mustflow 模板：包元数据、模板 manifest、文档示例，以及断言安装版本的测试。
+
+版本变更时，应根据 `sync_*` 偏好同步包元数据、模板 manifest 版本、文档示例和测试。
+
+## 命令执行策略
+
+不要从 `package.json`、`Makefile`、`justfile`、`Taskfile.yml` 或源码文件推断命令，应以 `.mustflow/config/commands.toml` 作为命令合同。
+
+仅当以下条件全部满足时，命令意图才可由代理执行：
+
+- `status = "configured"`
+- `lifecycle = "oneshot"`
+- `run_policy = "agent_allowed"`
+- `stdin = "closed"`
+- `timeout_seconds` 为正整数
+- 命令通过 `argv` 声明，或通过 `mode = "shell"` 和 `cmd` 声明
+- `cwd` 保持在当前 mustflow 根目录内
+
+`manual_only` 是新配置中的状态值。为兼容旧配置，可读取 `run_policy = "manual_only"`，但新模板应使用 `status = "manual_only"`。
+
+优先使用 `mf run <intent>`，以便项目在 `.mustflow/state/runs/latest.json` 中获得精简运行记录。
+
+串行运行 `mf run` 命令意图。当另一个已配置意图仍在运行时，不要启动第二个 `mf run`。声明了非空 `writes` 的意图是排他的验证阶段；运行其他 `mf run` 前，必须等待其完成。尤其当意图重写 `dist/` 等 package output 时，这一点尤为重要，因为本地 `mf` 可执行文件可能从该 output 加载。
+
+宿主 shell 可执行命令，但直接运行项目命令不自动视为 mustflow 验证。若命令绕过 `mf run`，除非用户明确批准手动例外且最终报告说明未生成 mustflow 运行回执，否则只能将其输出视为较低可信度的上下文。
+
+不要直接运行开发服务器、watcher、浏览器启动、交互式提示或后台进程，应报告被跳过的意图及原因。
+
+## 编辑策略
+
+改动应限于任务范围内，避免顺手重构（drive-by refactor）。不要修改 `.mustflow/config/mustflow.toml` 中受保护路径。
+
+遵循项目既有风格，若风格不明确，使用 `.mustflow/config/preferences.toml` 中的默认值。
+
+## 文档审阅队列
+
+当代理创建或修改面向用户、工作流、模板、上下文或 skill 文档时，除非用户明确要求不跟踪，否则使用 `mf docs review add <path>` 记录被触及的文档。队列存储在 `.mustflow/review/docs.toml`，仅在需要时创建。
+
+审阅可由人类、LLM、工具或外部流程完成。只记录宽泛的审阅者类型，以及审阅者 id、提供方、模型、命令意图和摘要等自由格式标识，不维护固定的具体 LLM 产品列表。
+
+使用 `mf docs review approve <path> --reviewer-kind <kind> --reviewer-id <id>` 可将已批准文档从默认审阅列表中隐藏，同时保留审阅记录。审阅者无法在批准时使用 `needs-human`；仅当仓库有意跳过审阅时使用 `ignore`。
+
+生成文件应通过工具刷新：
+
+- `REPO_MAP.md` 通过 `mf map --write`
+- `.mustflow/cache/mustflow.sqlite` 通过 `mf index`
+- `.mustflow/state/runs/latest.json` 通过 `mf run <intent>`
+
+## 验证
+
+检查时使用已配置的命令意图。常见意图名称包括：
+
+- `mustflow_check`
+- `test`
+- `lint`
+- `build`
+- `docs_validate`
+
+若预期意图缺失、禁用、仅手动可用或未配置，不要臆造替代方案，应明确报告跳过内容及原因。
+
+## 验证选择策略
+
+使用 `.mustflow/config/preferences.toml` 的 `[verification.selection]` 配置选择验证范围。此类偏好不授予命令执行权限，仅用于决定应考虑哪些已配置的命令意图。
+
+验证范围应与风险成比例。若已配置 `test_related`、`test_fast`、`build` 或文档专用检查，且能覆盖本次变更，应优先于宽泛测试套件使用。全量测试适用于跨领域行为、发布风险、缺少更窄覆盖或已配置策略明确要求的场景。若更窄意图合适但处于 `unknown`、`manual_only` 或缺失状态，应报告缺口，而非默默将最慢套件作为默认。
+
+- `strategy = "risk_based"`：优先选择覆盖变更行为、公开表面、命令合同和风险区域的最小检查。
+- `strategy = "targeted"`：除非用户、skill 或策略要求更广验证，否则优先选择直接相关检查。
+- `strategy = "full"`：优先使用完整且适用的已配置验证集合。
+- `prefer_related_tests = true`：在宽泛测试意图前，优先寻找更窄且相关的测试意图。
+- `skip_docs_only_full_test = true`：仅文档变更且文档验证覆盖相关表面时，可跳过宽泛测试。
+- `skip_translation_only_full_test = true`：仅翻译变更且源行为未变时，可跳过宽泛测试。
+- `skip_copy_only_full_test = true`：仅文案变更且行为、schema、模板、命令合同未变时，可跳过宽泛测试。
+- `report_skipped = true`：最终报告必须说明跳过的检查及原因。
+
+若证据显示行为、安全、数据、命令合同、发布输出或生成模板发生变化，不应用跳过偏好掩盖风险，应提升到相关已配置意图，或报告缺失所需意图。
+
+## 验证收紧机制
+
+不要为了“看起来完成”而削弱验证。
+
+代理不得：
+
+- 删除失败测试以通过检查
+- 未说明原因放宽断言
+- 跳过相关命令意图
+- 仅为规避失败将命令意图标记为 `not_applicable`
+- 在实现后变更验收标准
+
+当目标行为已变化、旧测试错误或新行为需要新增覆盖时，可更新测试，且必须在最终报告中说明此类变更。
+
+## 测试相关性策略
+
+测试是行为合同，不是永久工件。
+
+使用 `.mustflow/config/preferences.toml` 中的 `[testing.authoring]` 指导代理创建新测试的积极程度。默认值 `new_test_policy = "evidence_required"` 表示新测试应基于行为合同依据，如公开行为变化、回归风险、配置规则、schema 合同或安全/数据路径。此偏好仅指导测试编写行为，不削弱必要验证，也不能作为删除有效测试的理由。
+
+代理不得：
+
+- 仅因旧测试期望重新引入已移除行为
+- 为已故意移除的功能保留测试
+- 仅为通过验证删除失败测试
+- 未解释行为变化放宽断言
+- 仅为通过测试更新 snapshot
+
+当被测行为被有意移除、公开合同已变化、测试仅编码已移除实现细节、覆盖被更强测试重复或 snapshot 过时时，可更新或删除测试。
+
+测试新增、更新、删除或被识别为过时候，应报告行为合同、受影响测试、已运行命令、跳过的命令意图及剩余测试风险。
+
+## 预算、审批与隔离
+
+长时任务安全策略请使用 `.mustflow/config/mustflow.toml`。
+
+- `[budget]` 限制迭代次数、墙钟时间、命令运行次数、输出体量与重复失败次数。
+- `[approval]` 列出继续执行前必须人工审批的操作。
+- `[isolation]` 描述长时任务推荐的 worktree 或 sandbox 边界。
+
+达到预算上限或审批门槛时，应停止并报告。仅当仓库明确启用交接流程时使用 handoff，避免持续循环。
+
+若隔离策略要求独立 worktree 或 sandbox，不要在有脏改动的主 worktree 中运行长时自治任务。
+
+## 失败处理
+
+当命令失败时：
+
+1. 保留原始命令意图名称。
+2. 分析退出码并截取输出尾部。
+3. 识别最可能根因。
+4. 避免修改无关文件。
+5. 修复后重跑最有针对性的相关验证。
+6. 报告跳过检查及剩余风险。
+
+不要在 `.mustflow/` 中存储完整原始日志、密钥、客户数据或长转录。
+
+## 报告
+
+最终报告应包含：
+
+- 变更文件
+- 已执行的命令意图
+- 跳过的命令意图及原因
+- 验证结果
+- 剩余风险
+
+仅当 `.mustflow/config/preferences.toml` 允许时，才建议提交 commit。