signoff-cli 0.0.0-stage → 4.0.0

package/bin/signoff.js

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+"use strict";
+
+// SignOff (落印) CLI — dispatches to the five gates.
+// The gates are pure Node (lib/p1..p5.js). SIGNOFF_ENGINE=python falls back to
+// the reference implementation in gates/*.py, which is used only for parity tests.
+
+const { spawnSync } = require("child_process");
+const path = require("path");
+const fs = require("fs");
+
+// npm >= 11 gates postinstall behind an allowlist, so the install cannot be the only
+// way in: the first gate command in a repo finishes the job itself. Read-only commands
+// (doctor/status/explain/audit) and the hook path stay untouched - the hook path is what
+// the machine-wide guard uses, and there a light P1 is the whole point.
+const BOOTSTRAP_CMDS = new Set(["p1", "p2", "p3", "p4", "p5", "all", "guard", "secrets", "cov"]);
+function maybeBootstrap(cmd) {
+  if (!BOOTSTRAP_CMDS.has(cmd)) return;
+  if (process.env.SIGNOFF_NO_BOOTSTRAP === "1") return;
+  try {
+    const r = require("../lib/bootstrap").ensureRepo({ quiet: true });
+    if (r.installed && !process.argv.includes("--json")) {
+      console.error(`signoff: guarded ${require("path").basename(r.root)} automatically (${r.changed.join(", ")})`);
+    }
+  } catch (e) {
+    /* a convenience, never a verdict */
+  }
+}
+
+const GATES = {
+  p1: "p1_verify.py",
+  p2: "p2_coverage.py",
+  p3: "p3_queue.py",
+  p4: "p4_ledger.py",
+  p5: "p5_slop.py",
+};
+
+const HELP = `SignOff / 落印 — make "done" provable
+
+  signoff p1 [--run CMD]... [--budget SEC]   gate 1  verify before you speak
+  signoff p2 [--min-scenario N] [--md FILE]  gate 2  coverage has a level, not a vibe
+  signoff p3 [--cards DIR] plan|collect ...  gate 3  parallel work, no collisions
+  signoff p4 ask|confirm|verify|export ...   gate 4  risky actions leave a ledger
+  signoff p4 export --merge OTHER...        merge another repo's ledger into one table
+  signoff p4 export --format {md,json,csv}  pick the export shape
+  signoff p5 [FILES...]                      gate 5  empty words are a failure
+
+  signoff p1 --install-hook                  drop a git pre-commit hook
+  signoff all                                p1, p2, p5, then p4 verify
+  signoff doctor [--fix]                     show what is present; --fix repairs what it can prove
+
+  signoff init [--no-ci] [--prepare] [--quiet]  install hooks + CI so the gates run themselves
+  signoff init --share                       also write signoff.json, so every clone opts in
+  signoff init --chain | --lock-test | --reset-install   keep existing hooks / pin the
+                                             detected runner / move the install point to HEAD
+  signoff ensure [--global] [--json]         idempotent install; gates also self-install
+                                             (--global = guard every repo on this machine)
+  signoff guard [--full]                     run the gate set the hooks use (right now)
+  signoff status                             is this repo guarded?
+signoff doctor [--json] [--fix]            why is (or isn't) it guarded? --fix repairs it
+  signoff secrets [--staged|--all] [--json]   scan staged files for leaked credentials
+  signoff cov [--diff] [--min 80] [--json]   how much of this change the suite executed\n  signoff init --preset node|python|go|java   start from a curated gate config\n  signoff init --editor vscode               .vscode/tasks.json + problem matchers
+  signoff explain <p1..p5>                   what a gate checks and how it decides
+  signoff mcp                                serve the gates over stdio (MCP clients)
+  signoff audit [--range A..B] [--strict]    did the commits that landed carry a trailer?
+  signoff audit --since-install             only commits after the install point (refuses
+                                             a point that is not an ancestor of HEAD)
+  signoff uninstall [--keep-config] [--all]  remove hooks + CI workflow
+
+Requires Node >= 18 only; no Python. Options common to every gate: --json, -h.
+`;
+
+function python() {
+  return process.env.SIGNOFF_PYTHON || (process.platform === "win32" ? "python" : "python3");
+}
+
+function jsGate(name) {
+  const file = path.join(__dirname, "..", "lib", `${name}.js`);
+  return fs.existsSync(file) ? file : null;
+}
+
+function runGate(name, args) {
+  if (process.env.SIGNOFF_ENGINE !== "python" && jsGate(name)) {
+    try {
+      return require(jsGate(name)).run(args) || 0;
+    } catch (e) {
+      console.error(`signoff: ${name} failed: ${e && e.message}`);
+      return 1;
+    }
+  }
+  const file = path.join(__dirname, "..", "gates", GATES[name]);
+  if (!fs.existsSync(file)) {
+    console.error(`signoff: missing gate script ${file}`);
+    return 127;
+  }
+  const r = spawnSync(python(), [file, ...args], { stdio: "inherit" });
+  if (r.error) {
+    console.error(`signoff: cannot start ${python()} (${r.error.message}). Set SIGNOFF_PYTHON.`);
+    return 127;
+  }
+  return r.status === null ? 1 : r.status;
+}
+
+// Secrets run first in `all`: an unstaged key is worth more than a style report,
+// and a non-git directory has nothing to scan (exit 2 from secrets is not a failure).
+function runSecrets(args) {
+  try {
+    const inside = spawnSync("git", ["rev-parse", "--is-inside-work-tree"], {
+      cwd: process.cwd(),
+      encoding: "utf8",
+      windowsHide: true,
+    });
+    if (inside.status !== 0) return 0;
+    return require("../lib/secrets.js").run(["--json"]) || 0;
+  } catch (e) {
+    console.error(`signoff: secrets failed: ${e && e.message}`);
+    return 1;
+  }
+}
+
+function runAll(args) {
+  const steps = [
+    ["p1", args],
+    ["p2", args],
+    ["p5", []],
+    ["p4", ["verify"]],
+    // Coverage is opt-in on data: no coverage file means "not measured", not "failed".
+    ["cov", ["--allow-missing", "--diff"]],
+  ];
+  let code = 0;
+  console.log("\n== signoff secrets ==");
+  const sc = runSecrets(args);
+  if (sc !== 0) code = sc;
+  for (const [name, a] of steps) {
+    console.log(`\n== signoff ${name} ==`);
+    const c = runGate(name, a);
+    if (c !== 0) code = c;
+  }
+  return code;
+}
+
+function guard(sub, args) {
+  const file = path.join(__dirname, "..", "lib", "guard.js");
+  if (fs.existsSync(file)) {
+    try {
+      return require(file).main([sub, ...args]) || 0;
+    } catch (e) {
+      console.error(`signoff: guard failed: ${e && e.message}`);
+      return 1;
+    }
+  }
+  const py = path.join(__dirname, "..", "gates", "guard.py");
+  const r = spawnSync(python(), [py, sub, ...args], { stdio: "inherit" });
+  if (r.error) {
+    console.error(`signoff: cannot start ${python()} (${r.error.message}). Set SIGNOFF_PYTHON.`);
+    return 127;
+  }
+  return r.status === null ? 1 : r.status;
+}
+
+const [cmd, ...rest] = process.argv.slice(2);
+
+if (!cmd || cmd === "-h" || cmd === "--help" || cmd === "help") {
+  console.log(HELP);
+  process.exit(0);
+}
+if (cmd === "-v" || cmd === "--version" || cmd === "version") {
+  console.log(require("../package.json").version);
+  process.exit(0);
+}
+if (cmd === "doctor") process.exit(require("../lib/doctor").run(rest));
+if (cmd === "ensure") process.exit(require("../lib/bootstrap").run(rest));
+if (cmd === "all") {
+  maybeBootstrap("all");
+  process.exit(runAll(rest));
+}
+if (cmd === "init") process.exit(guard("init", rest));
+if (cmd === "guard") {
+  maybeBootstrap("guard");
+  process.exit(guard("guard", rest));
+}
+if (cmd === "hook") process.exit(guard("hook", rest));
+if (cmd === "status") process.exit(guard("status", rest));
+if (cmd === "uninstall") {
+  if (rest.includes("--global")) {
+    const r = require("../lib/bootstrap").uninstallGlobal();
+    console.log(r.removed ? `signoff: machine layer removed (${r.dir})` : "signoff: machine layer was not installed");
+    process.exit(0);
+  }
+  process.exit(guard("uninstall", rest));
+}
+if (cmd === "audit") {
+  try {
+    process.exit(require(path.join(__dirname, "..", "lib", "audit.js")).run(rest) || 0);
+  } catch (e) {
+    console.error(`signoff: audit failed: ${e && e.message}`);
+    process.exit(1);
+  }
+}
+if (cmd === "explain") process.exit(require("../lib/explain.js").run(rest));
+if (cmd === "cov") process.exit(require("../lib/cov.js").run(rest));
+if (cmd === "secrets") {
+  maybeBootstrap("secrets");
+  process.exit(require("../lib/secrets.js").run(rest));
+}
+if (cmd === "mcp") {
+  // stdio JSON-RPC; the module wires stdin and stays alive until the client closes it.
+  require("../integrations/mcp/server.js");
+  return;
+}
+if (GATES[cmd]) {
+  maybeBootstrap(cmd);
+  process.exit(runGate(cmd, rest));
+}
+
+console.error(`signoff: unknown command "${cmd}"\n`);
+console.error(HELP);
+process.exit(2);

package/docs/diagrams/README.md

@@ -0,0 +1,41 @@
+# SignOff 架构与生态图
+
+三张图全部由 **Mermaid** 生成（`mermaid-js/mermaid` + `mermaid-cli`），源文件在 `src/`，
+改文案只要改 `.mmd` 再渲染一次——不手画、不拼版、可 diff。
+
+| 源文件 | 产物 | 回答的问题 |
+| --- | --- | --- |
+| `src/signoff-1-capability.mmd` | `signoff-1-capability.png` | 由哪些部分组成、判定发生在哪一层、什么会留在仓库里 |
+| `src/signoff-2-market.mmd` | `signoff-2-market.png` | 已出现在哪些市场、哪些等审核、哪些物料备好未提交 |
+| `src/signoff-3-user.mmd` | `signoff-3-user.png` | 用户怎么装怎么用，以及平台/环境差异与已知坑 |
+
+## 重新生成
+
+```powershell
+$py = "$env:USERPROFILE\.openviking\venv\Scripts\python.exe"
+& $py "$env:USERPROFILE\.dsh\tools\diagram.py" doctor          # 检查 mmdc + Brave
+& $py "$env:USERPROFILE\.dsh\tools\diagram.py" render src --out . --size 2200 --theme neutral
+```
+
+这台机器上的全局规矩（`~/.dsh/AGENTS.md`「框架图」）：画图一律走这条链路。
+选 Mermaid 的理由是它是**可代码驱动**的图工具里星标最多的（91 028）；
+`excalidraw/excalidraw` 星更多（135 255）但它是画布应用，没有受支持的 headless CLI，结果不可复现。
+
+## 图 1 的读法
+
+从左到右：谁在调用 → 谁在判定 → 结果落在哪 → 依赖什么。要点：
+
+- 四个入口（CLI、git 钩子、CI、MCP/技能）**共用同一个 `guard.js`**，结论不会互相矛盾；
+- 五关并列，任一判红整体退出码就是 1，**没有“部分通过”**；
+- 提交信息里的 `Signoff-Pass: <tree>` 是审计的唯一线索，`--no-verify` 会让它消失（审计里显示 `missing`）。
+
+## 图 2 的读法
+
+绿色=已上线可被搜索/安装；黄色=已提交等人工审核；灰色=物料已备未提交。
+底部那句话是关键：**Registry 只是索引，不是流量**；真正带来访问的是人工清单与被引用。
+
+## 图 3 的读法
+
+上半部分是正常路径（安装 → 初始化 → 日常 → 排错 → 退出/边界），下半部分三支是
+平台差异、环境差异、已知坑。排错那一支刻意写成链条：`doctor → doctor --fix → explain <gate> → 改配置`，
+改阈值永远放最后——90% 的“没反应”是钩子没生效，不是阈值。

package/docs/diagrams/src/signoff-1-capability-en.mmd

@@ -0,0 +1,81 @@
+---
+title: SignOff capabilities and relations (v3.9.7)
+---
+flowchart LR
+  subgraph L1["① Entry · who calls it"]
+    direction TB
+    A1["CLI<br/>run · p1..p5 · init · status · doctor<br/>audit · explain · mcp · uninstall<br/>--json · --strict · --dry-run · --chain"]
+    A2["Git hooks<br/>pre-commit runs the gates<br/>commit-msg checks the trailer<br/>pre-push checks the audit window<br/>existing hooks chained as .local"]
+    A3["CI · signoff.yml<br/>same gates, second run<br/>fetch-depth 0 required for audit"]
+    A4["Agents<br/>5 MCP tools · one skill<br/>isError mirrors the exit code"]
+    A1 ~~~ A2 ~~~ A3 ~~~ A4
+  end
+
+  subgraph L2["② Dispatcher · guard.js decides what runs and what counts as pass"]
+    direction TB
+    D1["Parse<br/>cwd normalised to repo root<br/>SIGNOFF_* env · piped runs filtered"]
+    D2["Lock<br/>.signoff/lock/ dir + owner.json<br/>atomic mkdir; dead pid or >10 min reclaimed<br/>wait cap SIGNOFF_LOCK_WAIT_MS=8s"]
+    D3["Select gates<br/>five by default<br/>name p1..p5; a hook runs only its stage"]
+    D4["Verdict<br/>0 all pass · 1 any gate red · 2 usage or env<br/>no partial pass; --json emits the result"]
+    D1 ~~~ D2 ~~~ D3 ~~~ D4
+  end
+
+  subgraph L3["③ Five gates · each answers: read → decide → fix"]
+    direction TB
+    P1["P1 Tests<br/>read: config.test_cmd, else auto-detect<br/>decide: test exit code ≠ 0<br/>fix: pin the command in config"]
+    P2["P2 Coverage<br/>read: scenario files, assertion count<br/>decide: below threshold, or no assertions<br/>fix: add assertions; --strict is stricter"]
+    P3["P3 Queue<br/>read: status in tasks/id/card.json<br/>decide: not done, or fields missing<br/>fix: finish the card's acceptance criteria"]
+    P4["P4 Ledger<br/>read: audit.log hash chain + rollback commit<br/>decide: chain broken, rollback gone, trailer missing<br/>fix: p4 ask/confirm, or roll back"]
+    P5["P5 Anti-slop<br/>read: docs added by this change<br/>decide: placeholders · claims without evidence<br/>fix: add evidence or delete it"]
+    P1 ~~~ P2 ~~~ P3 ~~~ P4 ~~~ P5
+  end
+
+  subgraph L4["④ State machine · what happens inside one commit"]
+    direction TB
+    S1["pre-commit<br/>all five pass → marker {tree, mode} written"]
+    S2["commit-msg<br/>marker.tree == HEAD tree ?<br/>yes → append the Signoff-Pass trailer"]
+    S3["pre-push<br/>every commit in the audit window checked<br/>missing trailer = red"]
+    S4["CI<br/>gates + audit again<br/>no git identity means no fake pass"]
+    S1 ~~~ S2 ~~~ S3 ~~~ S4
+  end
+
+  subgraph L5["⑤ Artifacts · judgment leaves evidence"]
+    direction TB
+    F1["passed<br/>tree + mode(pass|skip) + ts<br/>invalidated when tree changes"]
+    F2["audit.log<br/>append-only hash chain: prevHash · action · rollback"]
+    F3["installed.json<br/>install-point sha / time / version<br/>left edge of the audit window"]
+    F4["commit message<br/>Signoff-Pass: tree<br/>--no-verify is the only hole"]
+    F5["config.json<br/>thresholds · test command · P5 word list"]
+    F1 ~~~ F2 ~~~ F3 ~~~ F4 ~~~ F5
+  end
+
+  subgraph L6["⑥ External dependencies · only two are hard requirements"]
+    direction TB
+    X1["Node ≥ 18<br/>pure JS · no build step · no native modules"]
+    X2["git<br/>hook location · history · ancestor checks"]
+    X3["Test runner<br/>whatever the repo uses; falls back when absent"]
+    X4["Python · peer tests only<br/>never invoked at runtime"]
+    X5["GitHub Actions<br/>optional, --no-ci skips it"]
+    X1 ~~~ X2 ~~~ X3 ~~~ X4 ~~~ X5
+  end
+
+  L1 -->|calls| L2
+  L2 -->|picks gates per stage| L3
+  L3 -->|writes marker / trailer| L4
+  L4 -->|persists| L5
+  L5 -->|audit comparison| L6
+
+
+  classDef entry fill:#eef3fb,stroke:#2f6fdd,stroke-width:1.4px,color:#0f2d5c
+  classDef sched fill:#fdf3e7,stroke:#b45309,stroke-width:1.4px,color:#5c2c05
+  classDef gate fill:#e8f7f0,stroke:#0e9f6e,stroke-width:1.4px,color:#0b4a33
+  classDef state fill:#eef2ff,stroke:#4f46e5,stroke-width:1.4px,color:#312e81
+  classDef data fill:#f3ecfd,stroke:#7c3aed,stroke-width:1.4px,color:#3d1e6b
+  classDef ext fill:#f4f5f7,stroke:#6b7280,stroke-width:1.2px,color:#374151
+  classDef note fill:#ffffff,stroke:#0f172a,stroke-dasharray:4 3,color:#0f172a
+  class A1,A2,A3,A4 entry
+  class D1,D2,D3,D4 sched
+  class P1,P2,P3,P4,P5 gate
+  class S1,S2,S3,S4 state
+  class F1,F2,F3,F4,F5 data
+  class X1,X2,X3,X4,X5 ext

package/docs/diagrams/src/signoff-1-capability.mmd

@@ -0,0 +1,84 @@
+---
+title: SignOff 完整能力与关系（v3.9.7）
+---
+flowchart LR
+  subgraph L1["① 入口层 · 谁在调用它"]
+    direction TB
+    A1["CLI<br/>run · p1..p5 · init · status · doctor<br/>audit · explain · mcp · uninstall<br/>--json · --strict · --dry-run · --chain"]
+    A2["Git 钩子<br/>pre-commit 跑闸门<br/>commit-msg 查 trailer<br/>pre-push 查审计窗口<br/>已有钩子链式为 .local"]
+    A3["CI · signoff.yml<br/>同一套闸门再跑一遍<br/>fetch-depth 0 才能审计"]
+    A4["Agent 面<br/>MCP 五工具 · 技能<br/>isError 跟随退出码"]
+    A1 ~~~ A2 ~~~ A3 ~~~ A4
+  end
+
+  subgraph L2["② 调度层 · guard.js 决定跑什么、谁算通过"]
+    direction TB
+    D1["解析<br/>cwd 归一到仓库根<br/>SIGNOFF_* 环境 · 管道点 filtered"]
+    D2["取锁<br/>.signoff/lock/ 目录 + owner.json<br/>mkdir 原子；死进程或超 10 分钟回收<br/>等待上限 SIGNOFF_LOCK_WAIT_MS=8s"]
+    D3["选关<br/>默认五关全跑<br/>可点名 p1..p5；钩子只跑本阶段该跑的"]
+    D4["定判决<br/>0 全过 / 1 任一关红 / 2 用法或环境错<br/>--json 输出结构化结果"]
+    D1 ~~~ D2 ~~~ D3 ~~~ D4
+  end
+
+  subgraph L3["③ 五关 · 每关都回答：读什么 → 判什么 → 怎么修"]
+    direction TB
+    P1["P1 测试<br/>读：config.test_cmd，否则自动识别<br/>判：测试命令退出码 ≠ 0<br/>修：把命令固化进 config"]
+    P2["P2 覆盖<br/>读：场景文件数与断言数<br/>判：低于阈值，或声称成功却无断言<br/>修：补断言；--strict 更严"]
+    P3["P3 队列<br/>读：tasks/id/card.json 的 status<br/>判：不是 done，或字段缺失<br/>修：把卡片验收条件做完"]
+    P4["P4 账本<br/>读：audit.log 哈希链 + 回滚点提交<br/>判：链断、回滚点消失、审计缺 trailer<br/>修：p4 ask/confirm 补记或回滚"]
+    P5["P5 反空话<br/>读：本次新增的文档<br/>判：占位符（词边界）· 无证据结论 · 空话词<br/>修：给证据或删句子"]
+    P1 ~~~ P2 ~~~ P3 ~~~ P4 ~~~ P5
+  end
+
+  subgraph L4["④ 状态机 · 一次提交里发生了什么"]
+    direction TB
+    S1["pre-commit<br/>五关全过 → 写 marker {tree, mode}"]
+    S2["commit-msg<br/>marker.tree == HEAD tree ?<br/>是 → 追加 Signoff-Pass trailer"]
+    S3["pre-push<br/>审计窗口内提交逐个查<br/>缺 trailer 即红"]
+    S4["CI<br/>再跑五关 + 审计<br/>无 git 身份时不冒充通过"]
+    S1 ~~~ S2 ~~~ S3 ~~~ S4
+  end
+
+  subgraph L5["⑤ 产物与记录 · 判断留下证据"]
+    direction TB
+    F1["passed<br/>tree + mode(pass|skip) + ts<br/>tree 变了自动失效"]
+    F2["audit.log<br/>只追加哈希链：prevHash · action · rollback"]
+    F3["installed.json<br/>安装点 sha / 时间 / 版本<br/>审计窗口左边界"]
+    F4["提交信息<br/>Signoff-Pass: tree<br/>--no-verify 的唯一破绽"]
+    F5["config.json<br/>阈值 · 测试命令 · P5 词表"]
+    F1 ~~~ F2 ~~~ F3 ~~~ F4 ~~~ F5
+  end
+
+  subgraph L6["⑥ 外部依赖 · 只有两样是硬要求"]
+    direction TB
+    X1["Node ≥ 18<br/>纯 JS · 无构建 · 无原生模块"]
+    X2["git<br/>钩子位置 · 提交历史 · 祖先校验"]
+    X3["测试运行器<br/>仓库自己那一套；缺失则退化后备命令"]
+    X4["Python · 仅对等测试<br/>运行时永不调用"]
+    X5["GitHub Actions<br/>可选，--no-ci 跳过"]
+    X1 ~~~ X2 ~~~ X3 ~~~ X4 ~~~ X5
+  end
+
+  L1 -->|调用| L2
+  L2 -->|按阶段选关| L3
+  L3 -->|写 marker / trailer| L4
+  L4 -->|落盘| L5
+  L5 -->|审计比对| L6
+
+  N["退出码即判决：0 通过 · 1 判红 · 2 用法与环境<br/>没有“部分通过”这回事"]
+  L2 -.-> N
+
+  classDef entry fill:#eef3fb,stroke:#2f6fdd,stroke-width:1.4px,color:#0f2d5c
+  classDef sched fill:#fdf3e7,stroke:#b45309,stroke-width:1.4px,color:#5c2c05
+  classDef gate fill:#e8f7f0,stroke:#0e9f6e,stroke-width:1.4px,color:#0b4a33
+  classDef state fill:#eef2ff,stroke:#4f46e5,stroke-width:1.4px,color:#312e81
+  classDef data fill:#f3ecfd,stroke:#7c3aed,stroke-width:1.4px,color:#3d1e6b
+  classDef ext fill:#f4f5f7,stroke:#6b7280,stroke-width:1.2px,color:#374151
+  classDef note fill:#ffffff,stroke:#0f172a,stroke-dasharray:4 3,color:#0f172a
+  class A1,A2,A3,A4 entry
+  class D1,D2,D3,D4 sched
+  class P1,P2,P3,P4,P5 gate
+  class S1,S2,S3,S4 state
+  class F1,F2,F3,F4,F5 data
+  class X1,X2,X3,X4,X5 ext
+  class N note

package/docs/diagrams/src/signoff-2-market-en.mmd

@@ -0,0 +1,72 @@
+---
+title: SignOff publishing and market distribution (2026-11-07)
+---
+flowchart LR
+  subgraph SRC["⓪ Single source of truth · everything else is a projection"]
+    direction TB
+    R1["GitHub master<br/>source · hook templates · CI · docs"]
+    R2["npm tarball dsh-signoff@3.9.7<br/>package.json carries mcpName"]
+    R3["server.json + smithery.yaml<br/>raw material for listings"]
+    R4["docs/diagrams/src/*.mmd<br/>the diagrams are sources too"]
+    R1 ~~~ R2 ~~~ R3 ~~~ R4
+  end
+
+  subgraph PUB["① Publish channels · where content is actually downloadable"]
+    direction TB
+    C1["npm registry<br/>dsh-signoff · latest 3.9.7<br/>the only install path"]
+    C2["GitHub Releases<br/>v3.9.7 bilingual notes + tgz"]
+    C3["Official MCP Registry<br/>io.github.ayuanxx-max/signoff@3.9.7<br/>mcpName verified"]
+    C4["OpenViking docs<br/>viking://resources/dsh/signoff-*"]
+    C1 ~~~ C2 ~~~ C3 ~~~ C4
+  end
+
+  subgraph IDX["② Indexes and lists · whether anyone can find you"]
+    direction TB
+    subgraph IDXP["submitted / happens automatically"]
+      direction TB
+      I1["awesome-mcp-servers · PR #18813<br/>Developer Tools · human review 1–3 days"]
+      I2["Glama · auto-indexes the repo and scores it<br/>the listing carries its badge"]
+      I1 ~~~ I2
+    end
+    subgraph IDXR["not submitted yet · material ready"]
+      direction TB
+      I3["Smithery · smithery.yaml ready<br/>needs GitHub OAuth on the web"]
+      I4["mcp.so · PulseMCP<br/>mostly pull the official registry, usually automatic"]
+      I5["ClawHub skills market<br/>skill written, not published"]
+      I6["other awesome-* lists<br/>git-hooks / pre-commit / ai-agents"]
+      I3 ~~~ I4 ~~~ I5 ~~~ I6
+    end
+  end
+
+  subgraph SEE["③ Discovery · where users actually come from"]
+    direction TB
+    V1["GitHub search and topics<br/>11 topics set"]
+    V2["click from a curated list"]
+    V3["word of mouth / posts / comparisons"]
+    V4["npm search: dsh-signoff"]
+    V1 ~~~ V2 ~~~ V3 ~~~ V4
+  end
+
+  N1["Key distinction: registry and lists are indexes, they generate no traffic<br/>traffic comes from curated lists, citations and search hits"]
+  N2["Progress: channels 4/4 done<br/>indexes = 1 in review + 1 automatic + 1 submittable + 1 synced + 2 not submitted"]
+
+  SRC -->|publish| PUB
+  PUB -->|register as discoverable| IDX
+  IDX -->|someone sees it| SEE
+  C3 -.->|downstream sync| I4
+  C2 -.->|auto-indexed| I2
+  IDX -.-> N1
+  IDX -.-> N2
+
+  classDef src fill:#0f172a,stroke:#0f172a,color:#ffffff
+  classDef pub fill:#dcfce7,stroke:#0e9f6e,stroke-width:1.4px,color:#14532d
+  classDef pending fill:#fef3c7,stroke:#d97706,stroke-width:1.4px,color:#7c2d12
+  classDef todo fill:#f1f5f9,stroke:#94a3b8,stroke-width:1.2px,color:#334155
+  classDef see fill:#eef2ff,stroke:#4f46e5,stroke-width:1.3px,color:#312e81
+  classDef note fill:#ffffff,stroke:#0f172a,stroke-dasharray:4 3,color:#0f172a
+  class R1,R2,R3,R4 src
+  class C1,C2,C3,C4 pub
+  class I1,I2 pending
+  class I3,I4,I5,I6 todo
+  class V1,V2,V3,V4 see
+  class N1,N2 note

package/docs/diagrams/src/signoff-2-market.mmd

@@ -0,0 +1,72 @@
+---
+title: SignOff 发布与市场分布（2026-11-07）
+---
+flowchart LR
+  subgraph SRC["⓪ 唯一事实源 · 其余都是它的投影"]
+    direction TB
+    R1["GitHub 仓库 master<br/>源码 · 钩子模板 · CI · 文档"]
+    R2["npm tarball dsh-signoff@3.9.4<br/>package.json 带 mcpName"]
+    R3["server.json + smithery.yaml<br/>市场清单的原料"]
+    R4["docs/diagrams/src/*.mmd<br/>图也是源文件"]
+    R1 ~~~ R2 ~~~ R3 ~~~ R4
+  end
+
+  subgraph PUB["① 发布渠道 · 内容在这里真正可下载"]
+    direction TB
+    C1["npm registry<br/>dsh-signoff · latest 3.9.4<br/>唯一安装入口"]
+    C2["GitHub Releases<br/>v3.9.4 中英双语 + tgz"]
+    C3["官方 MCP Registry<br/>io.github.ayuanxx-max/signoff@3.9.4<br/>已过 mcpName 校验"]
+    C4["OpenViking 文档库<br/>viking://resources/dsh/signoff-*"]
+    C1 ~~~ C2 ~~~ C3 ~~~ C4
+  end
+
+  subgraph IDX["② 索引与目录 · 决定别人能不能找到你"]
+    direction TB
+    subgraph IDXP["已提交 / 会自动发生"]
+      direction TB
+      I1["awesome-mcp-servers · PR #18813<br/>Developer Tools 分类 · 人工审核 1–3 天"]
+      I2["Glama · 按仓库自动建索引并出分<br/>列表条目自带它的徽章"]
+      I1 ~~~ I2
+    end
+    subgraph IDXR["还没提交 · 物料已备"]
+      direction TB
+      I3["Smithery · smithery.yaml 已就绪<br/>需 GitHub OAuth 在网页提交"]
+      I4["mcp.so · PulseMCP<br/>多拉官方 registry，通常自动收录"]
+      I5["ClawHub 技能市场<br/>技能已写好，未发布"]
+      I6["其余 awesome-* 清单<br/>git-hooks / pre-commit / ai-agents"]
+      I3 ~~~ I4 ~~~ I5 ~~~ I6
+    end
+  end
+
+  subgraph SEE["③ 发现入口 · 用户实际从哪里进来"]
+    direction TB
+    V1["GitHub 搜索与 topics<br/>11 个 topic 已配"]
+    V2["清单页点击"]
+    V3["别人转述 / 文章 / 对比表"]
+    V4["npm 站内搜索 dsh-signoff"]
+    V1 ~~~ V2 ~~~ V3 ~~~ V4
+  end
+
+  N1["关键区分：Registry 与目录是索引，不产生流量<br/>流量来自人工清单、被引用、被搜索命中"]
+  N2["进度：发布渠道 4/4 完成<br/>索引 = 1 待审 + 1 自动 + 1 可提交 + 1 同步 + 2 未提交"]
+
+  SRC -->|发布| PUB
+  PUB -->|登记为可发现| IDX
+  IDX -->|被人看到| SEE
+  C3 -.->|下游同步| I4
+  C2 -.->|自动建索引| I2
+  IDX -.-> N1
+  IDX -.-> N2
+
+  classDef src fill:#0f172a,stroke:#0f172a,color:#ffffff
+  classDef pub fill:#dcfce7,stroke:#0e9f6e,stroke-width:1.4px,color:#14532d
+  classDef pending fill:#fef3c7,stroke:#d97706,stroke-width:1.4px,color:#7c2d12
+  classDef todo fill:#f1f5f9,stroke:#94a3b8,stroke-width:1.2px,color:#334155
+  classDef see fill:#eef2ff,stroke:#4f46e5,stroke-width:1.3px,color:#312e81
+  classDef note fill:#ffffff,stroke:#0f172a,stroke-dasharray:4 3,color:#0f172a
+  class R1,R2,R3,R4 src
+  class C1,C2,C3,C4 pub
+  class I1,I2 pending
+  class I3,I4,I5,I6 todo
+  class V1,V2,V3,V4 see
+  class N1,N2 note