技能 编程开发 Witness修复回归追踪

Witness修复回归追踪

v20260928
witness
使用确定性Ed25519见证清单,对修复标记回归进行签名、验证和随时间追踪。适用于任何项目——克隆工具包、运行初始化、注册修复、在每次发布时重新生成。
获取技能
241 次下载
概览

Witness — cryptographic fix-regression tracking

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:

  1. Inside ruflo — used by ruflo's own CI to gate publishes (see

.github/workflows/v3-ci.yml job witness-verify).

  1. 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.

Quick start (any project)

# One-time bootstrap — creates verification.md.json,
# verification-history.jsonl, and witness-fixes.json template
node plugins/ruflo-core/scripts/witness/init.mjs --root .

# Edit witness-fixes.json: add { id, desc, file, marker } per fix.
# A "marker" is a distinctive substring that MUST appear in `file`
# while the fix is present. If someone reverts the fix, the marker
# disappears and `verify` reports it as `regressed`.

# Regenerate the manifest (signing requires @noble/ed25519)
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

# Or authenticate the manifest and check source markers in a clean clone.
# Generated dist/ entries are explicitly reported as skipped.
node plugins/ruflo-core/scripts/witness/verify.mjs \
  --manifest verification.md.json --source-only

# For a CI hash tripwire, also fail when a file changes but its marker remains.
node plugins/ruflo-core/scripts/witness/verify.mjs \
  --manifest verification.md.json --source-only --strict

Without --strict, marker-preserving SHA drift is reported but exits 0.
--strict makes that drift exit 1 without changing signature or missing-file checks.

Temporal queries (ADR-103)

# Latest snapshot vs. previous
node plugins/ruflo-core/scripts/witness/history.mjs \
  --history verification-history.jsonl summary

# 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
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.

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.

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.

In ruflo's CI

v3-ci.yml job witness-verify runs after the behavioral smoke tests
and before publish. Failure modes:

FailureCause
signatureValid: nomanifest hand-edited; re-run regen
regressed: > 0a documented fix lost its marker since issuance
missing: > 0a cited dist file no longer exists; rebuild or remove the entry
scope: source-onlysignature + source markers checked; generated entries intentionally skipped
信息
分类 编程开发
名称 witness
版本 v20260928
大小 4.75KB
更新时间 2026-09-30
语言