| name | sf-change-control |
| description | StoryMoss 变更门禁与不可破坏项。何时加载：要提交/推送代码、要 bump 版本、要改架构边界、要动数据库迁移、要改 CI、要发布 tag、要合并 feature 分支、或被问“能不能直接改/直接推”时。也用于判断一个改动是否需要用户授权（R10）。 |
StoryMoss 变更控制
本项目已有一套带血泪史的强制规则。先读这一条再动手：违反任何一条都会触发 CI 失败、用户返工、或已修复的 bug 复活。
不可破坏项（每条都附历史事故）
| 规则 | 要求 | 违反的代价（已发生） |
|---|
| 版本号四源统一 | git tag、src-tauri/Cargo.toml、src-tauri/tauri.conf.json、src-frontend/package.json 版本一致 | 升级器/CI 版本探测错位；release 产物版本与 tag 不符 |
| 每次推送必更新文档 | 同步更新 README.md、CHANGELOG.md、AGENTS.md、PROJECT_STATUS.md、ROADMAP.md、ARCHITECTURE.md、TESTING.md、docs/USER_GUIDE.md | 用户依据陈旧文档诊断，反复返工 |
| 推送后必查 CI | 推送后立即 gh run list --limit 3，监控到全绿（见 sf-validation-and-qa） | v0.26.19–.21 多版本积压的 macOS 公证过期、Windows WiX 中文文件名问题，因“推完就走”拖了多版才被发现 |
| tag 不覆盖 | git tag -a vX.Y.Z -m "..." && git push origin vX.Y.Z，禁止 force push 已有 tag | 升级器 latest.json 指向错乱 |
| 迁移文件名 ASCII 短名 | 新迁移文件名只允许 V###__ascii_short.sql，禁止中文/全角标点/破折号，长度尽量短 | v0.26.21：WiX light.exe 标识符生成失败导致 Windows MSI 整个构建挂掉 |
| 后台 LLM 调用必须静默化 | 任何后台（非用户等待路径）LLM 调用的 context_label 必须加入 is_silent_background 白名单（src-tauri/src/llm/service.rs） | v0.23.45 / v0.26.23：后台 Ingest/auto_contract 进度事件覆盖前端主活动，导致“正文已返回但界面卡死” |
| 不要把后台 DB 写入同步阻塞 tokio worker | record_llm_call 等高频 DB 写入走 spawn_blocking fire-and-forget | v0.23.19：600s 超时，pool.get() 无限阻塞 |
std::sync::Mutex 不可重入 | 同一线程持锁期间禁止再次 lock 同一锁；中毒锁用 unwrap_or_else(|e| e.into_inner()) 恢复 | v0.23.34 select_candidates 自死锁；v0.23.42 BGP-4 自死锁 |
不动 rustfmt.toml 跨平台行为 | 不要开启 format_strings（macOS/Windows nightly 行为不一致） | CI cargo +nightly fmt -- --check 在不同平台结果不同 |
| 架构边界 | python3 scripts/architecture_guard.py 必须通过；db 禁止依赖 narrative/agents/memory/creative_engine/story_system/pipeline；domain 禁止依赖任何业务模块；禁止重新引入 FORBIDDEN_GLOBALS（VECTOR_STORE/DB_POOL/LLM_SERVICE/APP_CONFIG/SKILL_MANAGER/...） | v0.23.1 单例清零与循环依赖斩断的成果回潮 |
变更分类与门禁
提交门 vs 推送门：下表是提交门禁（能否 commit）。推送一律触发推送门：四源版本号统一 + docs of record 同步（AGENTS.md 强制规则 4）+ 推送后必查 CI（sf-validation-and-qa / .cursor/rules/post-push-ci-check.mdc），与变更类别无关。即便是"可逆/本地"类，一旦 push 就走完整推送门。
| 类别 | 例子 | 提交门 |
|---|
| 可逆 / 本地 | 单文件 bug 修复、新增测试、注释 | 本地 cargo test --lib + npx tsc --noEmit + cargo +nightly fmt -- --check + npm run format:check 全绿即可提交 |
| 跨层 | 改 IPC 命令、SyncEvent variant、DTO | 必须跑 scripts/verify-ipc-manifest.py；前端 assertUnreachable 兜底；ts-rs 重新生成 |
| 跨层共享算法 | 改 trim_self_repetition（Rust）或 trimSelfRepetition（TS） | 必须双跑 tests/fixtures/trim_golden.json（Rust trim_self_repetition_matches_shared_golden_fixture + TS textCleanup.golden.test.ts） |
| 架构边界 | 改 db ↔ narrative 依赖、重新引入全局单例 | architecture_guard.py 必须通过；HIGH 风险需用户授权（R10） |
| 数据库迁移 | 新增 .sql 文件 | 文件名 ASCII 短名 V###__*.sql；幂等（duplicate column/already exists 跳过）；本地 cargo test --lib 跑迁移测试 |
| 用户契约 / 不可逆 | 改 quick phase 30-60s 返回首章的承诺、改 tag 策略、改升级器端点 | R10：必须用户授权；先在 ROADMAP 记录为债务并量化 |
提交信息格式
<type>: <subject>
type: feat / fix / docs / style / refactor / test / chore
历史风格见 git log --oneline -30：fix: v0.26.23 修复...、feat: v0.26.19 ...。
何时 NOT 用本技能
- 纯探索 / 读代码 → 用
sf-architecture-contract 或 sf-reference。
- 调试具体 bug → 用
sf-debugging-playbook。
- 改完后要跑哪些测试 → 用
sf-validation-and-qa。
- 发布流程的命令解剖 → 用
sf-run-and-operate。
出处与维护
- 强制规则来源：
CLAUDE.md（META charter + Zero-Pause）、AGENTS.md（强制构建规则）、.cursor/rules/post-push-ci-check.mdc。
- 重验证命令：
git log --oneline -5（看最近提交风格与版本号）grep -rE '^version' src-tauri/Cargo.toml src-frontend/package.json（四源版本是否一致；另查 tauri.conf.json 的 "version"）python3 scripts/architecture_guard.py（边界是否仍通过）gh run list --limit 3（最近 CI 状态）
- 易漂移项：版本号（每次发布必查）、CI workflow（
.github/workflows/build.yml）、is_silent_background 白名单（src-tauri/src/llm/service.rs）。
- 最后核对：2026-07-07，v0.26.23。
