signoff-cli 0.0.0-stage → 4.0.0

package/docs/diagrams/src/signoff-3-user-en.mmd

@@ -0,0 +1,94 @@
+---
+title: "User path: install, use, troubleshoot (0 → 5 is the order)"
+---
+flowchart TB
+  subgraph ROW1["User path · strictly 0 → 5; red = must do, amber = the places people trip on"]
+    direction LR
+    subgraph T0["0 · Precheck"]
+      direction TB
+      T0a["node -v ≥ 18<br/>git --version works"]
+      T0b["run at the repo root<br/>(where .git lives)"]
+      T0c["Windows / macOS / Linux all fine"]
+    end
+    subgraph T1["1 · Install"]
+      direction TB
+      T1a["npm i -g dsh-signoff"]
+      T1b["no global install: npx dsh-signoff p1 once"]
+      T1c["behind a corporate proxy set npm proxy<br/>or npx cannot fetch the package"]
+    end
+    subgraph T2["2 · Init"]
+      direction TB
+      T2a["signoff init"]
+      T2b["repo already has husky hooks: add --chain<br/>otherwise yours get replaced"]
+      T2c["test command differs per machine: --lock-test"]
+      T2d["see what it will write: --dry-run"]
+      T2e["leave CI alone: --no-ci"]
+    end
+    subgraph T3["3 · Daily commits"]
+      direction TB
+      T3a["git commit<br/>pre-commit runs the five gates"]
+      T3b["marker and trailer written only when all five pass"]
+      T3c["status: what got installed<br/>doctor: why it does nothing"]
+      T3d["explain p2: how this gate decides"]
+      T3e["audit --since-install: who really passed"]
+    end
+    subgraph T4["4 · Red? check in this order"]
+      direction TB
+      T4a["doctor: are the hooks running at all"]
+      T4b["not running → init --chain"]
+      T4c["tests really fail → fix code, not thresholds"]
+      T4d["coverage short → add assertions, or --strict for the stricter verdict"]
+      T4e["queue incomplete → finish the card"]
+      T4f["ledger broken / trailer missing → p4 ask/confirm or roll back"]
+      T4g["P5 false positive → rewrite the wording, not the word list"]
+    end
+    subgraph T5["5 · Upgrade and uninstall"]
+      direction TB
+      T5a["upgrade: npm i -g dsh-signoff@latest<br/>then signoff init to refresh the hooks"]
+      T5b["uninstall default: remove hooks, keep config"]
+      T5c["--keep-config / --all: two more thorough levels"]
+    end
+    T0 --> T1 --> T2 --> T3 --> T4 --> T5
+  end
+
+  subgraph ROW2["The three real-world dimensions · they do not change your flow, they change what you see"]
+    direction LR
+    subgraph PL["Platform differences"]
+      direction TB
+      PL1["Windows: hooks launch through .ps1 / .cmd<br/>exec bit irrelevant; a GBK console mangles Chinese output"]
+      PL2["macOS / Linux: hooks need the exec bit<br/>init sets it, doctor --fix repairs it"]
+      PL3["containers / CI: often no user.name or user.email<br/>the commit fails and it is unrelated to the gates"]
+      PL4["SMB / NFS: lock atomicity cannot be proven<br/>mkdir beats O_EXCL, still best effort"]
+    end
+    subgraph EN["Environment differences"]
+      direction TB
+      EN1["Node 18 / 20 / 22 / 26 all tested in CI"]
+      EN2["shallow clone: audit baseline unreachable → red<br/>CI needs fetch-depth 0"]
+      EN3["monorepo: the repo root is the unit<br/>per-package init creates two hook sets"]
+      EN4["repo without tests: reports 'no test command detected'<br/>it never fakes a pass"]
+      EN5["works offline: the gates never touch the network<br/>only npx needs it"]
+    end
+    subgraph RED["Red lines · do not"]
+      direction TB
+      RD1["--no-verify → the audit shows missing"]
+      RD2["SIGNOFF_SKIP=1 → the marker records skip"]
+      RD3["loosening thresholds to turn red green = deleting the evidence"]
+    end
+  end
+
+  PL ~~~ EN ~~~ RED
+
+  ROW1 -->|same verdicts, different symptoms| ROW2
+
+  classDef stage fill:#eef3fb,stroke:#2f6fdd,stroke-width:1.6px,color:#0f2d5c
+  classDef must fill:#fee2e2,stroke:#dc2626,stroke-width:1.5px,color:#7f1d1d
+  classDef step fill:#fbfcfe,stroke:#9aa4b2,stroke-width:1.1px,color:#1f2937
+  classDef warn fill:#fef3c7,stroke:#d97706,stroke-width:1.2px,color:#7c2d12
+  classDef env fill:#eef2ff,stroke:#4f46e5,stroke-width:1.1px,color:#312e81
+  classDef bad fill:#fee2e2,stroke:#b91c1c,stroke-width:1.3px,color:#7f1d1d
+  class T0a,T1a,T2a,T3a,T3b stage
+  class T1c,T2b,T2c,T4a,T4b,T4c must
+  class T0b,T0c,T1b,T2d,T2e,T3c,T3d,T3e,T4d,T4e,T4f,T4g,T5a,T5b,T5c step
+  class PL1,PL2,PL3,PL4 warn
+  class EN1,EN2,EN3,EN4,EN5 env
+  class RD1,RD2,RD3 bad

package/docs/diagrams/src/signoff-3-user.mmd

@@ -0,0 +1,92 @@
+---
+title: 用户路径：安装、使用、排错（0→5 是先后顺序）
+---
+flowchart TB
+  subgraph ROW1["用户路径 · 严格按 0 → 5 的先后；红色是必做，黄色是你容易踩的"]
+    direction LR
+    subgraph T0["0 · 前置检查"]
+      direction TB
+      T0a["node -v ≥ 18<br/>git --version 可用"]
+      T0b["在仓库根执行<br/>（.git 所在目录）"]
+      T0c["Windows / macOS / Linux 都行"]
+    end
+    subgraph T1["1 · 安装"]
+      direction TB
+      T1a["npm i -g dsh-signoff"]
+      T1b["不想全局装：npx dsh-signoff p1 试一次"]
+      T1c["公司网络要先配 npm proxy<br/>否则 npx 取不到包"]
+    end
+    subgraph T2["2 · 初始化"]
+      direction TB
+      T2a["signoff init"]
+      T2b["仓库已有 husky 等钩子：加 --chain<br/>否则你的钩子会被顶掉"]
+      T2c["测试命令因机而异：加 --lock-test"]
+      T2d["先看会写什么：--dry-run"]
+      T2e["不想动 CI：--no-ci"]
+    end
+    subgraph T3["3 · 日常提交"]
+      direction TB
+      T3a["git commit<br/>pre-commit 自动跑五关"]
+      T3b["五关全过才写 marker 与 trailer"]
+      T3c["status：装了什么<br/>doctor：为什么没生效"]
+      T3d["explain p2：这一关到底怎么判"]
+      T3e["audit --since-install：谁真的过了"]
+    end
+    subgraph T4["4 · 红了怎么办（按这个顺序查）"]
+      direction TB
+      T4a["doctor：钩子真的在跑吗"]
+      T4b["没在跑 → init --chain"]
+      T4c["测试真失败 → 修代码，别调阈值"]
+      T4d["覆盖不足 → 补断言，或 --strict 看更严结论"]
+      T4e["队列未完成 → 把卡片做完"]
+      T4f["账本断链 / 缺 trailer → p4 ask/confirm 或回滚"]
+      T4g["P5 误报 → 改写措辞，不改词表"]
+    end
+    subgraph T5["5 · 升级与卸载"]
+      direction TB
+      T5a["升级：npm i -g dsh-signoff@latest<br/>再跑 signoff init 刷新钩子"]
+      T5b["uninstall 默认：摘钩子、留配置"]
+      T5c["--keep-config / --all：更彻底两档"]
+    end
+    T0 --> T1 --> T2 --> T3 --> T4 --> T5
+  end
+
+  subgraph ROW2["现实世界的三个维度 · 不改你的流程，但会改变你看到的现象"]
+    direction LR
+    subgraph PL["平台差异"]
+      direction TB
+      PL1["Windows：钩子用 .ps1 / .cmd 启动器<br/>执行位不生效；控制台 GBK 会把中文显示成乱码"]
+      PL2["macOS / Linux：钩子必须有执行位<br/>init 会设，doctor --fix 能补"]
+      PL3["容器 / CI：常无 user.name、user.email<br/>提交失败与闸门无关"]
+      PL4["SMB / NFS：锁的原子性无法被证明<br/>mkdir 比 O_EXCL 可靠，仍属尽力而为"]
+    end
+    subgraph EN["环境差异"]
+      direction TB
+      EN1["Node 18 / 20 / 22 / 26 都在 CI 测过"]
+      EN2["浅克隆：审计基线不可达 → 判红<br/>CI 必须 fetch-depth 0"]
+      EN3["monorepo：以仓库根为准<br/>子包各自 init 会出现两套钩子"]
+      EN4["无测试仓库：如实报“未识别到测试命令”<br/>不假装通过"]
+      EN5["离线可用：闸门不联网，只有 npx 取包要网"]
+    end
+    subgraph RED["红线 · 不要碰"]
+      direction TB
+      RD1["--no-verify 绕过 → 审计显示 missing"]
+      RD2["SIGNOFF_SKIP=1 → marker 记 skip，留痕"]
+      RD3["改阈值让红变绿 = 把证据删掉"]
+    end
+  end
+
+  ROW1 -->|同一套判定，换环境会换现象| ROW2
+
+  classDef stage fill:#eef3fb,stroke:#2f6fdd,stroke-width:1.6px,color:#0f2d5c
+  classDef must fill:#fee2e2,stroke:#dc2626,stroke-width:1.5px,color:#7f1d1d
+  classDef step fill:#fbfcfe,stroke:#9aa4b2,stroke-width:1.1px,color:#1f2937
+  classDef warn fill:#fef3c7,stroke:#d97706,stroke-width:1.2px,color:#7c2d12
+  classDef env fill:#eef2ff,stroke:#4f46e5,stroke-width:1.1px,color:#312e81
+  classDef bad fill:#fee2e2,stroke:#b91c1c,stroke-width:1.3px,color:#7f1d1d
+  class T0a,T1a,T2a,T3a,T3b stage
+  class T1c,T2b,T2c,T4a,T4b,T4c must
+  class T0b,T0c,T1b,T2d,T2e,T3c,T3d,T3e,T4d,T4e,T4f,T4g,T5a,T5b,T5c step
+  class PL1,PL2,PL3,PL4 warn
+  class EN1,EN2,EN3,EN4,EN5 env
+  class RD1,RD2,RD3 bad

package/docs/gates.en.md

@@ -0,0 +1,105 @@
+# Gates — SignOff
+
+> 中文: [gates.md](gates.md)
+
+One command per gate. Each writes `.signoff/pN.json`; exit 0 passes, 1 fails, 2 is a usage or precondition problem.
+
+## P1 `gates/p1_verify.py`
+
+| flag | meaning |
+| --- | --- |
+| `--run CMD` (repeatable) | command to run; when omitted, `signoff guard` supplies the detected runner |
+| `--budget SEC` | budget for all commands together, default 180 s |
+| `--install-hook` | write `.git/hooks/pre-commit` containing `exec signoff p1` |
+| `--json` / `--quiet` | machine-readable output / errors only |
+
+Output: `{"gate":"p1","ok":true,"elapsedMs":39,"budgetMs":180000,"cases":3,...}`. The case count is the largest number found in `N passed` / `N tests` / `N checks` / `N assertions`.
+
+## Runner detection (`lib/detect.js`, 3.7.0)
+
+`signoff guard` never guesses silently. It resolves a command in this order and prints where the answer came from:
+
+1. `test_cmd` in `.signoff/config.json` (set with `--test-cmd`);
+2. `package.json` → `scripts.test`, unless it says `no test specified`;
+3. `package.json` dependencies → `vitest` / `jest` / `mocha` (`npx --no-install …`);
+4. `Cargo.toml` → `cargo test --quiet`;
+5. `go.mod` → `go test ./...`;
+6. `Makefile` with a `test:` target → `make test`;
+7. python tests (`tests/test_*.py` or `test_*.py` anywhere) → `python -m pytest -q`, else `python -m unittest discover -q`, else a hint that no interpreter exists.
+
+An empty `tests/` directory is not a suite. When tests exist but nothing can run them, `init` / `status` / `doctor` say so instead of reporting a silent skip.
+
+## P2 `gates/p2_coverage.py`
+
+Scans the root plus `packages/` and `apps/` for directories with a `package.json` or `verify/`. Levels:
+
+- `scenario`: `verify/scenarios/*.json` all parse and at least one has a `checks` array;
+- `harness`: only pages under `verify/`;
+- `smoke`: only a `package.json`;
+- `missing`: none of the above.
+
+| flag | meaning |
+| --- | --- |
+| `--strict` | fail unless every directory reaches `scenario` |
+| `--min-scenario N` / `--min-assertions N` | thresholds |
+| `--md FILE` | write a Markdown coverage table |
+
+## P3 `gates/p3_queue.py`
+
+Cards live in `tasks/<id>/card.json` by default:
+
+```json
+{"id":"t1","goal":"fix the menu","scope":["client.js"],"acceptance":["menu 11/11"],"rollback":"v0.9.34"}
+```
+
+| subcommand | behaviour |
+| --- | --- |
+| `validate` | five fields present, ids unique, scope is an array of strings |
+| `plan` | cards whose scopes overlap go into different waves; prints the wave list |
+| `collect --changed FILES` | every changed file must be claimed by a card; also lists cards that claimed work but shipped nothing |
+
+## P4 `gates/p4_ledger.py`
+
+Actions are limited to `config` / `profile` / `publish`. The ledger is scoped per repository: `.signoff/audit.log` inside a repo (falling back to `~/.signoff/audit.log` outside one; `SIGNOFF_HOME` forces a directory). Each record carries a `repo` field, and `verify` only checks rollback points for the current repo.
+
+| subcommand | behaviour |
+| --- | --- |
+| `ask --action --target [--ttl]` | issue a single-use ticket, 600 s by default |
+| `confirm --ticket --decision allow\|deny [--detail] [--rollback]` | consume the ticket and append a hash-chained entry; `deny` is recorded too and exits 1 |
+| `verify` | recompute the chain (`prev` + content hash) and check that the rollback point is an existing git ref; free text fails |
+| `export --out FILE [--merge OTHER...] [--format {md,json,csv}]` | export the ledger; each `--merge` file is re-verified independently and a broken chain is reported with exit 1 |
+
+An entry looks like `{"ts":...,"action":"publish","target":"x@1.0.0","detail":"...","rollback":"v1.0.0","decision":"allow","prev":"<sha256>","hash":"<sha256>"}`.
+
+## P5 `gates/p5_slop.py`
+
+Six rules: `placeholder` (`TODO`, `TBD`, `FIXME`, `待补`, `待定`), `ai-word` (`赋能`/`闭环`/`抓手`/`颗粒度`/`全链路` …), `absolute-claim` (`100%`/`零缺陷`/`永不`/`绝对`/`完美`/`彻底`/`极致`/`无缝`), `empty-adverbs` (two or more in one line), `claim-without-number` (`已验证`/`已覆盖`/`全部通过`/`全绿` on a line with no number), and missing rollback (P4 only).
+
+Fenced code and table rows starting with `|` are skipped so examples are not flagged. `--allow <rule>` relaxes one rule.
+
+## Auto-guard (2.0.0)
+
+After `signoff init`, `pre-commit` / `pre-push` / CI all call `signoff guard`:
+
+| what is staged | gates that actually run |
+| --- | --- |
+| docs (README, `docs/`) | P5 |
+| a detected test runner | P1 |
+| `verify/scenarios/` | P2 `--strict` |
+| a ledger (`.signoff/audit.log` or `~/.signoff/audit.log`) | P4 `verify` |
+
+`.signoff/cache.json` is keyed by `git write-tree`, so the same staged tree is judged once. `SIGNOFF_SKIP=1` skips and appends to `.signoff/skips.log`; `git commit --no-verify` is git's own hole and leaves no record, which is why CI is the boundary that cannot be bypassed.
+
+A chained (`--chain`) hook keeps its language: `.py`/`.js`/`.ps1`/`.cmd` suffixes pick the interpreter, and the plain `.local` name still runs first (3.9.0).
+
+Since 3.9.1 the lock is a directory holding `owner.json`, taken with `mkdir` (atomic on SMB/NFS, unlike O_EXCL create); a 3.9.0 lock file is still recognised.
+
+Since 3.8.0 one hook run at a time holds `.signoff/lock`; a live holder makes the second run exit 1 with the holder's pid, and a lock from a dead pid or older than 10 minutes is broken.
+
+## Audit boundary
+
+`audit --since-install` first checks that the install point is an ancestor of HEAD. After a rebase, a force-push or a fresh clone it is not, so the command exits 2 instead of reporting a window that covers the wrong commits; `signoff init --reset-install` moves the boundary to HEAD.
+
+## Runtime (3.0.0 and later)
+
+All five gates and the guard are Node (`lib/p1..p5.js`, `lib/guard.js`); Node 18+ is the only requirement, with no Python fallback. `gates/*.py` is a parity reference only (`npm run parity`).

package/docs/gates.md

@@ -0,0 +1,88 @@
+# Gates — SignOff / 落印
+
+> English: [gates.en.md](gates.en.md)
+
+每关一条命令，结果写 `.signoff/pN.json`，退出码 0 通过、1 失败、2 用法或前置条件问题。
+
+## P1 `gates/p1_verify.py`
+
+| 参数 | 含义 |
+| --- | --- |
+| `--run CMD`（可重复） | 要执行的命令；缺省：有 `tests/` 用 `python -m pytest tests -q`，否则 `npm test --silent` |
+| `--budget SEC` | 全部命令合计预算，默认 180 秒 |
+| `--install-hook` | 写 `.git/hooks/pre-commit`，内容为 `exec signoff p1` |
+| `--json` / `--quiet` | 机器可读输出 / 只报错 |
+
+输出：`{"gate":"p1","ok":true,"elapsedMs":39,"budgetMs":180000,"cases":3,...}`。用例数从 `N passed` / `N tests` / `N checks` / `N assertions` 里取最大值。
+
+## P2 `gates/p2_coverage.py`
+
+扫描根目录与 `packages/`、`apps/` 下带 `package.json` 或 `verify/` 的目录。级别：
+
+- `scenario`：`verify/scenarios/*.json` 全部可解析且至少一个 `checks` 数组；
+- `harness`：只有 `verify/` 下的页面；
+- `smoke`：只有 `package.json`；
+- `missing`：都没有。
+
+| 参数 | 含义 |
+| --- | --- |
+| `--strict` | 任一目录没到 `scenario` 即失败 |
+| `--min-scenario N` / `--min-assertions N` | 阈值 |
+| `--md FILE` | 写 Markdown 覆盖表 |
+
+## P3 `gates/p3_queue.py`
+
+卡片默认在 `tasks/<id>/card.json`：
+
+```json
+{"id":"t1","goal":"修菜单","scope":["dsh-session-fork-tree/client.js"],"acceptance":["menu 11/11"],"rollback":"v0.9.34"}
+```
+
+| 子命令 | 行为 |
+| --- | --- |
+| `validate` | 五个字段齐全、id 不重复、scope 为字符串数组 |
+| `plan` | scope 前缀或通配相交的卡不同波，输出 wave 列表 |
+| `collect --changed FILES` | 每个改动文件必须被某张卡认领；同时列出“改了却没交东西”的卡 |
+
+## P4 `gates/p4_ledger.py`
+
+动作类别固定为 `config` / `profile` / `publish`，账本按仓库隔离：仓库内 `.signoff/audit.log`（非仓库目录退回 `~/.signoff/audit.log`，`SIGNOFF_HOME` 可强制指定）。每条记录带 `repo` 字段，`verify` 只校验本仓库的回滚点。
+
+| 子命令 | 行为 |
+| --- | --- |
+| `ask --action --target [--ttl]` | 发票据，单次使用，默认 600 秒过期 |
+| `confirm --ticket --decision allow\|deny [--detail] [--rollback]` | 消费票据并追加哈希链条目；`deny` 也记账，退出码 1 |
+| `verify` | 复算链（`prev` + 内容哈希），并校验回滚点是存在的 git ref；自由文本回滚点判失败 |
+| `export --out FILE [--format {md,json,csv}]` | 导出账本；md 是表格，json 是记录数组，csv 是一行一条 |
+
+条目形如 `{"ts":...,"action":"publish","target":"x@1.0.0","detail":"...","rollback":"v1.0.0","decision":"allow","prev":"<sha256>","hash":"<sha256>"}`。
+
+## P5 `gates/p5_slop.py`
+
+六条规则：`placeholder`（未完成的占位标记：`TODO`、`TBD`、`FIXME`、`待补`、`待定`）、`ai-word`（`赋能`/`闭环`/`抓手`/`颗粒度`/`全链路`…）、`absolute-claim`（`100%`/`零缺陷`/`永不`/`绝对`/`完美`/`彻底`/`极致`/`无缝`）、`empty-adverbs`（一行两个及以上空副词）、`claim-without-number`（`已验证`/`已覆盖`/`全部通过`/`全绿` 所在行没有数字）、缺回滚（仅 P4 使用）。
+
+跳过 fenced code 与以 `|` 开头的表格行，避免把示例当空话。`--allow <rule>` 可放行某条规则。
+
+## 自动守护（2.0.0）
+
+`signoff init` 之后，`pre-commit` / `pre-push` / CI 都会调 `signoff guard`：
+
+| 场景 | 实际跑的关 |
+| --- | --- |
+| 暂存的文档（README、docs/ 下） | P5 |
+| 能探到测试命令（package.json 的 test，或 pytest） | P1 |
+| 存在 `verify/scenarios/` | P2 `--strict` |
+| 存在账本（仓库内 `.signoff/audit.log` 或 `~/.signoff/audit.log`） | P4 `verify` |
+
+缓存文件 `.signoff/cache.json` 以 `git write-tree` 的结果为键：同一份暂存内容重复提交只判一次。
+`SIGNOFF_SKIP=1` 跳过并写 `.signoff/skips.log`；`git commit --no-verify` 是 git 自身口子，无记录，因此 CI 是不可绕过的边界。
+
+> 自检记录（2026-11-06）：装好 `signoff init` 后，本条修正在 `pre-commit` 里跑过 P1（30 用例）与 P5（3 份文档 0 命中）。
+
+## 运行环境（3.0.0 起）
+
+## 审计边界
+
+`audit --since-install` 先确认安装点是 HEAD 的祖先；rebase、强推、换克隆后对不上会退 2，用 `signoff init --reset-install` 把边界挪到当前 HEAD。
+
+五关与守卫都是 Node 实现（`lib/p1..p5.js`、`lib/guard.js`），只需要 Node 18+；不再依赖 Python，也没有降级模式。`gates/*.py` 仅作为对拍参考（`npm run parity`）。

package/docs/integrations.md

@@ -0,0 +1,58 @@
+# 接入方式（同一套判决，六种入口）
+
+落印不绑定平台：任何一个能跑命令的地方都能接入，判决与退出码一致（0 通过、1 红、2 用法/环境）。
+
+## 1. 本机零接触（最快）
+
+```bash
+npm i -g signoff-cli && cd your-repo && signoff init
+```
+
+之后 `git commit` 自动过闸。
+
+## 2. GitHub Actions
+
+```yaml
+- uses: ayuanxx-max/dsh-signoff@v3.15.0
+  with:
+    args: all
+```
+
+红关会输出 `::error file=...,line=...` 注解并写步骤摘要。
+
+## 3. pre-commit
+
+```yaml
+repos:
+  - repo: https://github.com/ayuanxx-max/dsh-signoff
+    rev: v3.15.0
+    hooks:
+      - id: signoff-guard
+```
+
+## 4. lefthook
+
+```yaml
+pre-commit:
+  commands:
+    signoff:
+      run: signoff guard
+```
+
+## 5. husky
+
+```bash
+echo 'signoff guard' > .husky/pre-commit
+```
+
+## 6. VS Code
+
+```bash
+signoff init --editor vscode
+```
+
+生成 6 个任务与问题匹配器，红关直接落到 Problems 面板。
+
+## MCP
+
+`io.github.ayuanxx-max/signoff` 已在 MCP Registry，可被支持 MCP 的客户端直接调用。

package/docs/promotion.md

@@ -0,0 +1,71 @@
+# 推广：GitHub 上没有浏览时怎么办
+
+前提：这是一个**工具型**仓库，不是内容型。工具靠"被引用"传播，不靠刷。
+所以顺序是：先让仓库在 GitHub 内部可被检索到，再让外部渠道有人替你说一句话，最后才是发帖。
+
+## 第 0 层：GitHub 内部可发现性（今天就能做完，收益最确定）
+
+| 项 | 现状 | 应做 |
+| --- | --- | --- |
+| 仓库 description | mojibake（`SignOff 4e00 8bfa...`） | 改成一句英文 + 一句中文，含关键词 |
+| topics | **空** | 至少 8 个：`git-hooks` `pre-commit` `code-quality` `audit` `cli` `nodejs` `testing` `llm-agents` `ai-agents` `mcp` |
+| README 首屏 | 中文长文，无英文 | 顶部三行：一句话 + 安装 + 一张门禁输出；`README.en.md` 供非中文读者 |
+| Releases | 有 tarball，但说明只有几行 | 每个 Release 写安装 + 用法 + 变更（已按此改造） |
+| License | 确认存在 | 无 LICENSE 的仓库会被企业用户直接跳过 |
+
+GitHub 的搜索会索引 description、topics、README 正文；topics 为空等于不参与任何主题页。
+
+## 第 1 层：进入别人的清单（一次性的、长期有效的流量）
+
+优先级从高到低：
+
+1. **awesome-mcp-servers** —— 我们有真正的 MCP server，这类清单审核看"能不能跑"，通过率高。
+2. **awesome-git-hooks / awesome-pre-commit / awesome-static-analysis** —— 与本工具的定位完全对口。
+3. **awesome-claude-code / awesome-ai-agents** —— agent 工作流清单，signoff 的"证明 done"是它们的空白格。
+4. **awesome-nodejs**（门槛高、竞争大）——最后再试。
+
+提交方式：fork → 在对应分类加一行（一句话 + 链接）→ PR。**一行就够，别写广告词**，
+这类清单的维护者会直接关掉营销文案。
+
+## 第 2 层：内容（发一次，长期被搜到）
+
+英文主战场（选一个发，别群发）：
+
+- **Show HN**：标题不要写 "SignOff — a tool for X"。写结论：
+  `Show HN: A git hook that refuses to let an agent say "done" without proof`。
+  正文三段：问题（agent 说完成了，凭什么信）、做法（五关 + 账本 + 退出码即判决）、
+  一条真实输出。HN 会问"和 husky/lint-staged 有什么区别"，答案必须一句话说清。
+- **dev.to / r/git**：偏教程，`How to make "done" verifiable in a repo`。
+
+中文：
+
+- **V2EX / 掘金 / 知乎**：标题带痛点——"让 AI 写完代码说'完成'这件事，怎么验？"
+- 内容结构同上，附中文 README 链接。
+
+## 第 3 层：定位（决定别人要不要点开）
+
+不要和 lint 工具比，它们不判"完成"。可用的对比句：
+
+- husky / lefthook：**装钩子**，不决定钩子里跑什么、失败算什么；
+- pre-commit：**跑检查**，不产账本，也没有"这次提交真的过闸门了吗"的审计；
+- SignOff：把"完成"变成一个**可验证的判决**（退出码）+ 一条**可审计的链**（账本）。
+
+## 度量（别猜，读数据）
+
+```bash
+# 近 14 天浏览量/克隆量（需要 push 权限的 token）
+curl -s -H "Authorization: token $TOKEN" \
+  https://api.github.com/repos/ayuanxx-max/dsh-signoff/traffic/views
+# 每周 npm 下载
+curl -s https://api.npmjs.org/downloads/point/last-week/dsh-signoff
+```
+
+现实预期：这类工具前两周能到 20–50 star 就算不错；单个 awesome-list 收录常带来 10–30 star 的长尾。
+**不做**：买赞、互 star、群发私信——GitHub 会判定为 spam，收益为负。
+
+## 顺序建议
+
+1. 今天：description + topics + README.en.md（**这一步的投入产出比最高**）。
+2. 本周：三个 awesome-list PR。
+3. 有第一波 star 后：Show HN（先有社会证明再发帖，转化率差 2–3 倍）。
+4. 之后每月一次：Release 说明写成"这次解决了谁的什么问题"，Release 页面本身也会被搜到。

package/docs/signoff.schema.json

@@ -0,0 +1,108 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "signoff.json",
+  "description": "Repo-level opt-in for SignOff: a committed declaration makes every clone run the five gates without a local install step.",
+  "type": "object",
+  "properties": {
+    "gates": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": [
+          "p1",
+          "p2",
+          "p3",
+          "p4",
+          "p5"
+        ]
+      },
+      "description": "Documentation only; the guard always runs P1-P5."
+    },
+    "test_cmd": {
+      "type": "string",
+      "description": "Pinned test command. Omit it unless every clone has that runner."
+    },
+    "budget": {
+      "type": "number",
+      "description": "Seconds a gate may spend before it counts as a failure."
+    },
+    "docs": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "Docs paths P5 should read."
+    },
+    "pre_push": {
+      "type": "boolean",
+      "description": "Run the full set before a push too."
+    },
+    "secrets": {
+      "type": [
+        "boolean",
+        "object"
+      ],
+      "description": "Secret scanning before P1. false disables it; an object accepts {allow: [rule or rule:path]}."
+    },
+    "cache": {
+      "type": "boolean",
+      "description": "Cache the P1 verdict per staged tree (default true)."
+    },
+    "docsFast": {
+      "type": "boolean",
+      "description": "Skip the suite when every staged file is a document (default true)."
+    },
+    "coverage": {
+      "type": [
+        "boolean",
+        "object"
+      ],
+      "description": "Run signoff cov in the guard. true means min 80; {min: 90} sets the threshold.",
+      "properties": {
+        "min": {
+          "type": "number"
+        }
+      }
+    },
+    "sign": {
+      "type": "boolean",
+      "description": "Sign the commit trailer (needs a key)."
+    },
+    "sign_key": {
+      "type": "string",
+      "description": "Path to the private key used for trailers."
+    },
+    "p5": {
+      "type": [
+        "string",
+        "object"
+      ],
+      "description": "Rule pack for gate 5: \"zh\" (default), \"en\", \"both\", or {pack, rules, allow}.",
+      "properties": {
+        "pack": {
+          "type": "string",
+          "enum": [
+            "zh",
+            "en",
+            "both"
+          ]
+        },
+        "rules": {
+          "type": "string",
+          "description": "Path to an extra rule JSON."
+        },
+        "allow": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "checkpoint": {
+      "type": "boolean",
+      "description": "advance a signed ledger checkpoint after every passing run"
+    }
+  },
+  "additionalProperties": false
+}