Witness
- 567 installs
- 67k repo stars
- Updated August 4, 2026
- ruvnet/ruflo
witness is a Claude Code skill that signs, verifies, and tracks fix-marker regressions over time using a deterministic Ed25519 witness manifest for developers who need cryptographic proof that documented bug fixes remain
About
witness is a ruflo skill from ruvnet/ruflo that ships every release with a signed manifest listing documented fixes, each tracked by sha256 hash and a distinctive marker substring in source files. Commands init, regen, verify, and history bootstrap verification.md.json, witness-fixes.json, and verification-history.jsonl using Node scripts under plugins/ruflo-core/scripts/witness/. Ed25519 signatures derive from the current git commit so anyone can re-derive the public key and verify without a committed private key. history.mjs queries temporal JSONL snapshots to pinpoint the commit that introduced a regression. Developers reach for witness when CI must gate publishes on fix-marker presence—ruflo's own v3-ci.yml runs witness-verify—or when copying the toolkit into any project for release regression tracking.
- witness
Witness by the numbers
- 567 all-time installs (skills.sh)
- +6 installs in the week ending Aug 5, 2026 (Skillselion tracking)
- Ranked #741 of 4,347 Backend & APIs skills by installs in the Skillselion catalog
- Data as of Aug 5, 2026 (Skillselion catalog sync)
npx skills add https://github.com/ruvnet/ruflo --skill witnessAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 567 |
|---|---|
| repo stars | ★ 67k |
| Last updated | August 4, 2026 |
| Repository | ruvnet/ruflo ↗ |
How do you track fix regressions across releases?
Use witness for development tasks
Who is it for?
Developers gating release pipelines who need cryptographic proof that documented bug-fix markers remain in the codebase at each git commit.
Skip if: Teams needing only unit test coverage without signed fix-marker manifests or temporal regression bisection across releases.
When should I use this skill?
A release pipeline must sign, verify, or bisect fix-marker regressions using witness init, regen, verify, or history.
What you get
Signed verification.md.json manifest, witness-fixes.json registry, verification-history.jsonl timeline, and CI verify exit codes.
- verification.md.json manifest
- verification-history.jsonl
- witness-fixes.json registry
By the numbers
- Provides 4 CLI commands: init, regen, verify, and history
- Uses Ed25519 signatures and sha256 hashes per documented fix marker
Files
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). 2. 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 (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.jsonTemporal 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 --jsonsummary 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.jsonand
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:
| 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 |
Related skills
Lark Openapi ExplorerInstantly explore, test, and generate calls against the full Lark (Feishu) OpenAPI surface without leaving their agent workflow.493k
Lark EventConsume real-time events from Lark/Feishu as structured NDJSON streams inside AI agent workflows.387k16kLark Openapi ExplorerWhen an existing Lark/Feishu skill or CLI command cannot fulfill a specific requirement and they need to discover and invoke the exact native OpenAPI endpoint.386k16k
Just ScrapeQuickly search, crawl, extract structured JSON, or monitor web pages without writing custom scraping code.245k41Lark AppsQuery the current visibility and permission scope of a Lark (Feishu) app without writing HTTP client code.235k16k
Design An InterfaceGenerate multiple radically different interface or API designs in parallel before committing to one.188k198kHow it compares
Pick witness when releases need signed fix-marker proof across commits; use conventional test suites for behavioral coverage without marker-based regression tracking.
FAQ
What files does witness init create?
witness init creates verification.md.json for the signed manifest, verification-history.jsonl for temporal snapshots, and witness-fixes.json as a template registry where each fix entry includes id, desc, file, and a marker substring that must appear in source.
How does witness detect a fix regression?
witness verify greps each fix marker substring in the registered file. If a documented fix marker disappears from the live tree, verify reports the fix as regressed. history.mjs then bisects the JSONL timeline to find the introducing commit.