Home

SpecGit Wiki

SpecGit is a delivery binding and acceptance harness: bind a branch or worktree to forge issues and one pull request, then derive the verdict from real git, PR, and CI evidence. A delivery is done if and only if specgit finish exits 0. If the evidence can't be gathered, the answer is unknown, never accepted — SpecGit fails closed.

SpecGit 是一个交付绑定与验收护栏：把一个分支或 worktree 绑定到 forge issues 和一个 pull request，然后从真实的 git、PR 与 CI 证据推导出验收结论。交付完成的唯一标准是 specgit finish 退出码为 0。如果证据无法收集，结论是 unknown 而绝不是 accepted —— SpecGit 是 fail-closed（宁可报未知，不放行）的。

The model in one line · 一句话模型

execution context (branch or worktree) + issues[] + one PR (or MR) + required CI checks

One delivery, one PR, N issues. Evidence flows through your authenticated forge CLI — gh for GitHub, glab for declared self-managed GitLab. No tokens read, no telemetry.

一次交付 = 一个执行上下文 + N 个 issue + 一个 PR/MR + 必需的 CI 检查。证据通过你已认证的 forge CLI 获取 —— GitHub 用 gh，声明的自建 GitLab 用 glab。不读取 token，不做遥测。

Contents · 目录

Page · 页面	Content · 内容
Getting Started	Install, specgit init, first delivery · 安装、初始化、第一次交付
CLI Reference	Ten commands, exit-code contract (0/1/2/3/130), --json envelope · 十个命令、退出码契约、JSON 输出
Concepts	Three file tiers, delivery binding, fail-closed acceptance, one issue = one WHY · 三层文件模型、交付绑定、fail-closed 验收
Provider Architecture	Ports, gh/glab adapters, routing · 端口抽象、适配器、路由机制
GitLab Support	Version window, differences from GitHub · 版本范围、与 GitHub 的差异
Team Workflow	Delivery loop, policy as team contract, review · 交付循环、策略即团队契约、评审

Quick facts · 关键事实

• Repository · 仓库: https://github.com/LeXwDeX/SpecGit
• Install · 安装: npm install -g specgit (npm package specgit, current version 1.0.1)
• Requirements · 运行要求: Node.js ≥ 20.19.0, git, and gh (GitHub) or glab ≥ 1.113.0 (declared GitLab) authenticated
• Commands · 命令: init, setup, issue, pr, finish, bind, unbind, status, accept, doctor — ten, exactly
• Exit codes · 退出码: 0 accepted/success · 1 rejected · 2 usage error · 3 fail-closed unknown · 130 interrupted
• License · 许可证: MIT