Style Playbook Skills

Style Playbook Skills 是 Ivan style playbook 的 source-of-truth 仓库：它保存人工维护的 project snapshots、Topic packages、六个 global group Skills，以及用于浏览、筛选和触发生成任务的本地 library site。这个仓库不是普通文档站，而是“项目记忆 + Topic taxonomy + 机器索引 + Agent 分发面”的组合系统。README.md、config/style-playbook-groups.yaml 与 skills/style-playbook-write/SKILL.md 共同定义了写入 contract。

• Tags: Rust web service, React app, TypeScript web, System design docs, Quality gates, SQLite, Markdown style, Manual version release delivery
• Why / evidence: 这些 tags 来自 checked-out repo 和 catalog record。主要证据包括 README.md、Cargo.toml、migrations/、src/read_model.rs、src/codex.rs、src/db.rs、web/、skills/style-playbook-write/SKILL.md。Topic token 的大小写以对应技术/工作流的官方写法为准；slug 只作为稳定 ID，不直接充当项目标题。

• skills/style-playbook/references/projects/ 是人工 project memory；每个 snapshot 要能让后续 Agent 恢复项目目的、边界、运行方式、质量门禁和可复用决策。
• skills/style-playbook/references/topics/<slug>/ 是 Topic package 真相源，package-local assets/ 与 TOPIC.md 一起维护；tools/topic_skill_manager.py 根据 typed routing metadata 编译六个 global group Skills。
• skills/style-playbook-write/scripts/catalog.py 维护 references/data/**、候选报告、topic reports 和 audit；脚本只维护机器索引，不应替代人工 Markdown。
• src/ 是 Rust/Axum 读模型和本地站点后端；web/ 是 React/Vite UI；migrations/ 保存 SQLite schema，用于 generation run 与站点状态。

本地站点由 Rust binary 承载，Cargo.toml 依赖 axum、sqlx、tokio、tower-http、walkdir 等服务层组件；migrations/ 与 src/db.rs 说明 generation history 和站点状态使用 SQLite。前端属于嵌入式管理 UI，web/ 提供 React/TypeScript surface，最终由服务端读模型消费 skills/style-playbook/references/**。公开/内部读模型由 .github/workflows/ci-pr.yml 与 .github/workflows/ci-main.yml 构建检查，.github/workflows/release.yml 只通过单一 target dispatch 负责发布资产；字段变化必须考虑站点、skill 和 data JSON 三个消费面。

核心边界是“人工 Markdown 是知识、JSON 是索引、group Skill 是分发”。src/read_model.rs 解析 project snapshot 与 Topic package 的 typed frontmatter/sections，处理 display name、visibility、categories 和 routing。src/codex.rs 只生成 Codex launch prompt，并在成功后触发 sync-insights / rebuild-topics，不能把生成后的文本当作不可审查产物。catalog.py discover-topic-candidates 用 deterministic signals 补漏，但候选只能作为复核入口，不能替代 Topic package 本体。

基础门禁包括 catalog.py sync-insights、catalog.py rebuild-topics、catalog.py discover-topic-candidates --fail、catalog.py audit --fail、tools/topic_skill_manager.py build-fingerprints、static Release Contract Gate、Python tests、Rust tests、TypeScript typecheck 和 web build。Release 另外验证 trusted final baseline、固定 source、tag/Release/artifact identity、镜像 digest、实际 public export 和 manifest v1；本项目不创建 GitHub ref reservation 或 completion record。因为这个仓库本身决定后续 Agent 如何命名 Project/Topic，生成 prompt 与 audit 规则要一起验证。

Markdown 使用原生 dprint 与官方插件，通过 dprint.json 指定自然段单行与中文软换行合并。tools/markdown.py 提供 setup/check/fix/staged；lefthook.yml 在提交前只修复暂存 Markdown，并使用原生部分暂存恢复机制。PR/main CI 使用同一工具清单与配置执行检查；生成模板保持合规，格式基线独立于功能改动（skills/policies/markdown-style/、.github/workflows/ci-pr.yml、.github/workflows/ci-main.yml）。

• Project title 使用人类 display name，slug 只做稳定 ID；blog-26 这类仓库不能直接显示成 @owner/repo。
• Topic token 命名复用工程模式，并保留对应生态的官方大小写。
• Topic package 使用 <slug>/TOPIC.md，路由只允许配置文件登记的六个 global group；普通 Topic 不生成 leaf Skill。
• 候选发现只给证据驱动建议；真正提升为 Topic 仍要写 Definition、When to use 和 Habits / defaults。
• Markdown 样式规则由自包含 Policy 分发；提供方直接复用源包，其他项目明确安装与接入。正文自然段一行，代码/语法结构保留，hook 自动修复与 CI 只读检查使用同一固定工具清单。
• 发布入口采用一个 target 字段：常规值是主人选择的下一版意图 patch、minor 或 major，完整版本只作为主人明确指定的例外；版本数字由执行端 policy 依据 trusted final baseline 解析，不由 PR label、文件名或主人每次手填。
• Release unit 由最后一个已完成 final source（不含）到 dispatch 固定 github.sha（含）组成；tag、GitHub Release、镜像 digest 和公开资产必须绑定同一 source identity，项目不创建 reservation/completion refs，也不持久化 per-PR release evidence。
• SemVer compatibility classification 是可选的独立治理，不参与本项目的 target selection、release eligibility 或 durable release state；本项目不安装或调用 per-PR impact record / aggregation route。

• 最大风险是“索引刷新”被误认为“知识刷新”；Project/Topic Markdown 没有变时，站点只是换了数据壳。
• UI、Docker、SQLite 这类信号必须区分强弱，否则会把候选 Topic 变成噪音。
• 私有仓库 visibility 与公开导出要保持 fail-closed，不能因为 display metadata 暴露 checkout path。
• 真实 GitHub branch protection/ruleset API 不属于本项目 release identity 的额外存储合同；发布仍必须通过既有 branch、CI、签名和公开面门禁。

• README.md
• Cargo.toml
• migrations/
• src/read_model.rs
• src/codex.rs
• src/db.rs
• web/
• skills/style-playbook-write/SKILL.md
• tools/topic_skill_manager.py
• .github/workflows/ci-pr.yml
• .github/workflows/ci-main.yml
• .github/workflows/release.yml
• .github/release-contract.json
• tools/manual_release.py
• docs/adr/0007-manual-release-intent.md
• docs/specs/manual-version-release-delivery/SPEC.md
• dprint.json
• lefthook.yml
• tools/markdown.py