git-workflow skill package

这是一个面向人类维护者和 Agent 的 Git 工作流 skill 包。它用仓库本地 Git config/INI 配置描述 source profile、ordered targets 和 target refs，并提供 repo-local git-workflow CLI 来检查 Git 图、恢复长任务、独立推广和归档。

重要：本包不假设 main、master、main-local、release/*、prod 或 test。所有名称都必须由目标仓库的 .git-workflow/config 声明。wxapp-finance / weihaostudio-server 只作为随包模板示例。

核心约束

• Node.js 核心：CLI 要求 Node.js >= 20，只使用 Node.js 标准库和 Git；不需要 npm install、第三方 npm 包或网络服务。
• 配置格式：.git-workflow/config 是 Git config/INI。关系是 source pattern → profile → 有序 target 名称 → refs/heads/*。
• 独立推广：每个 target 都必须由同一个 source 当前 tip 独立执行普通双父 --no-ff merge；禁止 target → target 链式传播。
• Git 图归档证明：每个 target 既要通过 source-tip ancestry，又要在 target first-parent 历史中存在第二父等于 source 当前 tip 的普通双父 merge。
• 恢复检查：git-workflow resume-check 扫描当前本地、且匹配配置 source patterns 的 branch，报告 pending、archive-ready、blocked。
• 可选 Hook：Hook 只用于防呆，不能保证 Agent 载入 Skill，也不能替代用户批准、业务验收或远端保护。
• 删除授权：CLI 永远不自动删除 branch、worktree 或 remote ref；archive-ready 之后仍必须展示精确对象并取得用户明确确认。

包内容

• SKILL.md：给 Agent 的执行约束。创建 source/worktree、恢复长任务、归档和清理时必须调用 repo-local CLI。
• docs/requirements.md：产品需求和验收标准。
• docs/architecture.md：Node CLI、配置解析、Git 图算法、Hook 边界的技术设计。
• docs/operations.md：面向人类的安装、恢复、推广、归档和故障处理指南。
• references/config-format.md：配置字段、命令契约和退出码速查。
• references/newapi-fork-development.md：仅在明确处理 NewAPI fork 时加载的项目专用补充，不改变通用规则。
• templates/wxapp-finance-weihaostudio-server.config：仅为配置示例，不代表任何业务仓库已安装。
• hooks/：随包提供的可选本地防呆 Hook；不会由本 Skill 自动启用。

安装与运行

npm 发行版

git-workflow 裸包名已被 npm 以“与既有 git-work-flow 过于相似”为由拒绝；当前公开发行包使用 @weihaostudio/git-workflow。安装后提供的 CLI 命令仍是 git-workflow：

npm install --global @weihaostudio/git-workflow
git-workflow --help

# 不做全局安装时：
npx --yes @weihaostudio/git-workflow --help

全局或 npx CLI 只适合引导、诊断和显式安装 repo-local bundle。配置模式下，Agent 和维护者仍必须优先使用目标仓库内的 .git-workflow/bin/git-workflow，避免全局版本与仓库治理版本漂移。

目标仓库的 repo-local 入口

前提：目标仓库已由维护者审阅并提交 .git-workflow/config，且 repo-local git-workflow 已存在。

GIT_WORKFLOW=.git-workflow/bin/git-workflow
"$GIT_WORKFLOW" --help
"$GIT_WORKFLOW" doctor
"$GIT_WORKFLOW" discover

# 创建或接手长任务前
"$GIT_WORKFLOW" plan <source>
"$GIT_WORKFLOW" resume-check

# 每个 target 都独立使用同一个 source
"$GIT_WORKFLOW" promote <source> <target>

# 删除前只做检查，不会删除任何对象
"$GIT_WORKFLOW" archive-check <source>

resume-check 退出码：0=无 pending/blocked；1=有 pending 无 blocked；2=有 blocked；3=命令级失败。命令级失败的输出不能当作完整审计证据。

配置示例

[source "feature"]
    pattern = feature/*
    profile = standard

[target "verify"]
    ref = refs/heads/<configured-verify-ref>

[target "archive"]
    ref = refs/heads/<configured-archive-ref>

[profile "standard"]
    target = verify
    target = archive

重复 target key 的顺序只表示 profile 的有序目标列表，不表示 verify 可以 merge 到 archive。两个 target 都必须独立 merge 同一个 source。

npm 发布维护者清单

公开发布前必须依次完成：

1. 审阅 package.json 的 files 白名单；禁止打包 tests、docs、SKILL.md 和项目专用 references
2. npm pack --dry-run，再 npm pack，并审阅 tarball 文件清单与敏感数据扫描结果
3. 在洁净临时目录安装 tgz，验证 git-workflow --help、--version、init/doctor 与 install-hooks --yes
4. 确认 package 名、版本号、license、registry、公开范围与 npm 登录身份
5. npm publish --dry-run；获得发布人明确确认后才 npm publish
6. 在洁净环境通过 npm install -g 或 npx 做发布后验证，并创建对应 Git tag / Release 记录

CLI 运行时保持零第三方依赖；npm 仅是分发渠道，不是运行时依赖。

Hook 与清理

Hook 默认不安装。需要启用时先预览，再由仓库维护者明确确认：

"$GIT_WORKFLOW" install-hooks
"$GIT_WORKFLOW" install-hooks --yes

安装只提供本地防呆。linked worktree 尚未 checkout repo-local 文件时，Hook 会回退到共享仓库中已配置的 worktree 完成审计，避免内部 ref 初始化被误拒绝。删除 source 前必须先通过 git-workflow archive-check <source>，另行确认发布/用户验收，然后把要删除的精确 branch、worktree 路径和 remote ref 展示给用户并获得确认。没有确认时保留资源；不要用 --no-verify 或 Hook 存在替代审批。

Agent 与人类文档

• Agent 入口：SKILL.md
• 产品/技术/使用三类文档：docs/
• 配置和命令速查：references/config-format.md