witness

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Witness — cryptographic fix-regression tracking

Witness — 加密式修复回归跟踪

The witness toolkit lets you ship every release with a signed manifest that lists every documented fix in your codebase along with a sha256 + marker substring. Anyone with the same git commit can re-derive the public key and verify the signature without a committed private key.

A temporal history (JSONL) tracks how the fix population evolves across releases — so when a regression appears, you can pinpoint the commit that introduced it, not just "it's broken now."

This skill works two ways:

Inside ruflo — used by ruflo's own CI to gate publishes (see
```
.github/workflows/v3-ci.yml
```
job
```
witness-verify
```
).
In your own project — copy
```
plugins/ruflo-core/scripts/witness/
```
into your repo, run
```
init.mjs
```
, register your fixes in
```
witness-fixes.json
```
, and call
```
regen.mjs
```
from your release pipeline.

Witness工具包可让你在每次发布时附带一份已签名的清单，其中列出代码库中所有已记录的修复内容，以及对应的sha256值和标记子字符串。拥有相同git commit的任何人都可以重新生成公钥并验证签名，无需提交私钥。

时间历史记录（JSONL）会跟踪修复内容在各个版本中的演变情况——因此当出现回归时，你可以精准定位引入回归的提交记录，而不仅仅是知道“现在功能损坏了”。

该工具支持两种使用方式：

在ruflo内部使用——ruflo自身的CI流程会使用它来管控发布（参见
```
.github/workflows/v3-ci.yml
```
中的
```
witness-verify
```
任务）。
在你的项目中使用——将
```
plugins/ruflo-core/scripts/witness/
```
复制到你的仓库中，运行
```
init.mjs
```
，在
```
witness-fixes.json
```
中注册你的修复内容，并在发布流程中调用
```
regen.mjs
```
。

Quick start (any project)

快速开始（适用于任何项目）

bash

undefined

bash

undefined

One-time bootstrap — creates verification.md.json,

一次性初始化——创建verification.md.json,

verification-history.jsonl, and witness-fixes.json template

verification-history.jsonl和witness-fixes.json模板

node plugins/ruflo-core/scripts/witness/init.mjs --root .

Edit witness-fixes.json: add { id, desc, file, marker } per fix.

编辑witness-fixes.json：为每个修复添加{ id, desc, file, marker }字段。

A "marker" is a distinctive substring that MUST appear in

file

“标记”是一个独特的子字符串，当修复存在时必须出现在对应的

file

文件中。

while the fix is present. If someone reverts the fix, the marker

如果有人回退了修复，标记会消失，

verify

命令会将其标记为

regressed

（已回归）。

disappears and

verify

reports it as

regressed

重新生成清单（使用当前gitCommit的Ed25519密钥签名）

Regenerate the manifest (signs with Ed25519 from current gitCommit)

—

npm i @noble/ed25519 node plugins/ruflo-core/scripts/witness/regen.mjs
--manifest verification.md.json
--history verification-history.jsonl
--fixes witness-fixes.json

Verify markers are present in the live tree

验证标记是否存在于当前代码树中

node plugins/ruflo-core/scripts/witness/verify.mjs
--manifest verification.md.json

undefined

node plugins/ruflo-core/scripts/witness/verify.mjs
--manifest verification.md.json

undefined

Temporal queries (ADR-103)

时间查询（ADR-103）

bash

undefined

bash

undefined

Latest snapshot vs. previous

For each currently-regressed fix, find the commit that introduced it

针对当前所有已回归的修复，找出引入回归的提交记录

node plugins/ruflo-core/scripts/witness/history.mjs
--history verification-history.jsonl regressions

Status timeline for a specific fix

特定修复的状态时间线

node plugins/ruflo-core/scripts/witness/history.mjs
--history verification-history.jsonl timeline --id F1

Machine-readable for CI

适用于CI的机器可读格式

node plugins/ruflo-core/scripts/witness/history.mjs
--history verification-history.jsonl summary --json


`summary` exits non-zero if any fix newly regressed since the last
snapshot — drop it in CI as a soft pre-merge gate.

node plugins/ruflo-core/scripts/witness/history.mjs
--history verification-history.jsonl summary --json


`summary`命令会在自上次快照以来出现新的修复回归时返回非零退出码——你可以将其加入CI流程，作为预合并的软性管控环节。

Anti-patterns

反模式

Hand-editing
verification.md.json
— always regenerate via
```
regen.mjs
```
, otherwise the signature breaks.
Markers that are too generic (
```
'function'
```
,
```
'import'
```
) — pick something unique enough that
```
grep
```
doesn't false-positive against unrelated code.
Skipping the history append — without
```
--history
```
, you lose the ability to bisect when a regression was introduced.
Committing one without the other —
```
verification.md.json
```
and
```
verification-history.jsonl
```
belong in the same commit; the JSONL is what lets future you verify the signed manifest is the latest in the line.

手动编辑
verification.md.json
——始终通过
```
regen.mjs
```
重新生成，否则签名会失效。
过于通用的标记（如
```
'function'
```
、
```
'import'
```
）——选择足够独特的标记，避免
```
grep
```
在无关代码中产生误报。
跳过历史记录追加——如果不使用
```
--history
```
参数，你将失去定位回归引入时间的能力。
仅提交其中一个文件——
```
verification.md.json
```
和
```
verification-history.jsonl
```
应提交到同一个提交记录中；JSONL文件是让未来的你验证已签名清单是否为最新版本的依据。

Files

文件说明

```
scripts/witness/lib.mjs
```
— shared regenerate / history logic.
```
scripts/witness/regen.mjs
```
— CLI: sign + append history.
```
scripts/witness/history.mjs
```
— CLI: query the temporal log.
```
scripts/witness/init.mjs
```
— CLI: bootstrap into a fresh project.
```
scripts/witness/verify.mjs
```
— CLI: validate signature + markers.

```
scripts/witness/lib.mjs
```
——共享的重新生成/历史记录逻辑。
```
scripts/witness/regen.mjs
```
——CLI工具：签名并追加历史记录。
```
scripts/witness/history.mjs
```
——CLI工具：查询时间日志。
```
scripts/witness/init.mjs
```
——CLI工具：在新项目中初始化工具。
```
scripts/witness/verify.mjs
```
——CLI工具：验证签名和标记。

In ruflo's CI

在ruflo的CI流程中

v3-ci.yml

job

witness-verify

runs after the behavioral smoke tests and before

publish

. Failure modes:

Failure	Cause
`signatureValid: no`	manifest hand-edited; re-run regen
`regressed: > 0`	a documented fix lost its marker since issuance
`missing: > 0`	a cited dist file no longer exists; rebuild or remove the entry

v3-ci.yml

中的

witness-verify

任务会在行为冒烟测试之后、

publish

任务之前运行。失败场景如下：

失败情况	原因
`signatureValid: no`	清单被手动编辑；重新运行regen命令
`regressed: > 0`	自清单生成以来，某个已记录的修复丢失了其标记
`missing: > 0`	引用的分发文件已不存在；重新构建或移除该条目

witness

Original

Translation

Witness — cryptographic fix-regression tracking

Witness — 加密式修复回归跟踪

Quick start (any project)

快速开始（适用于任何项目）

One-time bootstrap — creates verification.md.json,

一次性初始化——创建verification.md.json,

verification-history.jsonl, and witness-fixes.json template

verification-history.jsonl和witness-fixes.json模板

Edit witness-fixes.json: add { id, desc, file, marker } per fix.

编辑witness-fixes.json：为每个修复添加{ id, desc, file, marker }字段。

A "marker" is a distinctive substring that MUST appear in
`file`

“标记”是一个独特的子字符串，当修复存在时必须出现在对应的
`file`
文件中。

while the fix is present. If someone reverts the fix, the marker

如果有人回退了修复，标记会消失，
`verify`
命令会将其标记为
`regressed`
（已回归）。

disappears and
`verify`
reports it as
`regressed`
.

重新生成清单（使用当前gitCommit的Ed25519密钥签名）

Regenerate the manifest (signs with Ed25519 from current gitCommit)

Verify markers are present in the live tree

验证标记是否存在于当前代码树中

Temporal queries (ADR-103)

时间查询（ADR-103）

Latest snapshot vs. previous

最新快照与上一版本对比

For each currently-regressed fix, find the commit that introduced it

针对当前所有已回归的修复，找出引入回归的提交记录

Status timeline for a specific fix

特定修复的状态时间线

Machine-readable for CI

适用于CI的机器可读格式

Anti-patterns

反模式

Files

文件说明

In ruflo's CI

在ruflo的CI流程中

witness

Original

Translation

Witness — cryptographic fix-regression tracking

Witness — 加密式修复回归跟踪

Quick start (any project)

快速开始（适用于任何项目）

One-time bootstrap — creates verification.md.json,

一次性初始化——创建verification.md.json,

verification-history.jsonl, and witness-fixes.json template

verification-history.jsonl和witness-fixes.json模板

Edit witness-fixes.json: add { id, desc, file, marker } per fix.

编辑witness-fixes.json：为每个修复添加{ id, desc, file, marker }字段。

A "marker" is a distinctive substring that MUST appear in file

“标记”是一个独特的子字符串，当修复存在时必须出现在对应的file文件中。

while the fix is present. If someone reverts the fix, the marker

如果有人回退了修复，标记会消失，verify命令会将其标记为regressed（已回归）。

disappears and verify reports it as regressed.

重新生成清单（使用当前gitCommit的Ed25519密钥签名）

Regenerate the manifest (signs with Ed25519 from current gitCommit)

Verify markers are present in the live tree

验证标记是否存在于当前代码树中

Temporal queries (ADR-103)

时间查询（ADR-103）

Latest snapshot vs. previous

最新快照与上一版本对比

For each currently-regressed fix, find the commit that introduced it

针对当前所有已回归的修复，找出引入回归的提交记录

Status timeline for a specific fix

特定修复的状态时间线

Machine-readable for CI

适用于CI的机器可读格式

Anti-patterns

反模式

Files

文件说明

In ruflo's CI

在ruflo的CI流程中

A "marker" is a distinctive substring that MUST appear in
`file`

“标记”是一个独特的子字符串，当修复存在时必须出现在对应的
`file`
文件中。

如果有人回退了修复，标记会消失，
`verify`
命令会将其标记为
`regressed`
（已回归）。

disappears and
`verify`
reports it as
`regressed`
.