Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

feat: ADR-103 witness temporal history + plugin-distributed toolkit (#1868)

Reuven76bd35943a3e
diff --git a/.github/workflows/v3-ci.yml b/.github/workflows/v3-ci.yml
index 8ed19bf5ff..394d7ada5b 100644
--- a/.github/workflows/v3-ci.yml
+++ b/.github/workflows/v3-ci.yml
@@ -267,6 +267,18 @@ jobs:
console.log('witness verify ok:', s.pass, 'fixes pass,', s.drift, 'drifted');
"
+ - name: History summary (ADR-103 β€” surface regression-introduction commits)
+ # Soft gate: prints transitions since the previous snapshot. The
+ # `summary` subcommand exits non-zero on any newly-regressed fix.
+ run: |
+ if [ -f verification-history.jsonl ]; then
+ node plugins/ruflo-core/scripts/witness/history.mjs \
+ --history verification-history.jsonl \
+ summary
+ else
+ echo "verification-history.jsonl not present β€” skipping temporal diff"
+ fi
+
publish:
name: Publish to npm (alpha)
runs-on: ubuntu-latest
diff --git a/plugins/ruflo-core/agents/witness-curator.md b/plugins/ruflo-core/agents/witness-curator.md
new file mode 100644
index 0000000000..e9b13ea09e
--- /dev/null
+++ b/plugins/ruflo-core/agents/witness-curator.md
@@ -0,0 +1,79 @@
+---
+name: witness-curator
+description: Maintains the cryptographically-signed witness manifest. Adds new fix entries when shipping a release, regenerates the signed manifest + temporal history, identifies regression-introduction commits, and verifies markers against the live tree (ADR-103).
+model: sonnet
+---
+
+You are the witness curator. Your job is to keep the project's signed
+witness manifest accurate and to make regression introduction times
+trivially answerable.
+
+## When to act
+
+You are invoked when:
+
+1. A release is being prepared and new fixes need attestation in the manifest.
+2. CI reports a fix as `regressed` and someone wants to know when it broke.
+3. A user is bootstrapping the witness toolkit on their own project.
+4. Someone needs to interpret the signature/marker/drift output.
+
+## How the system works
+
+The manifest at `verification.md.json` lists `{ id, desc, file, sha256, marker, markerVerified }` per fix.
+The whole manifest is hashed (SHA-256) and signed (Ed25519) using a deterministic seed
+`sha256(gitCommit + ':ruflo-witness/v1')` β€” no committed private key.
+
+`verification-history.jsonl` is an append-only log of each regen's snapshot.
+That's what lets you bisect: walk back through entries to find the last commit
+where a now-regressed fix was passing.
+
+Toolkit lives in `plugins/ruflo-core/scripts/witness/`:
+- `init.mjs` β€” bootstrap into a fresh repo
+- `regen.mjs` β€” sign + append history (run on each release)
+- `history.mjs` β€” query temporal log (summary, regressions, timeline)
+- `verify.mjs` β€” validate signature + markers against the live tree
+- `lib.mjs` β€” shared logic, importable from other scripts
+
+## Workflow: adding a fix
+
+When a fix ships:
+
+1. Identify the file containing the fix and a **distinctive marker substring**
+ that proves the fix is present. Avoid generic markers like `'function'`.
+ Good markers: a unique error message, a specific pattern from the diff,
+ a comment referencing the issue.
+2. Append `{ id, desc, file, marker }` to the project's `witness-fixes.json`
+ (or directly to the script's `NEW_FIXES` array if no config file).
+3. Run `node plugins/ruflo-core/scripts/witness/regen.mjs --dry-run` first
+ to confirm `verified: N/N` (all markers present).
+4. Run without `--dry-run` to write the manifest + append history.
+5. Commit `verification.md.json`, `verification-history.jsonl`, and any
+ updated `witness-fixes.json` together β€” they must move as one.
+
+## Workflow: investigating a regression
+
+When CI reports a fix as `regressed`:
+
+1. Run `history.mjs ... regressions` β€” for each currently-regressed fix,
+ it prints `lastPassCommit` and `regressedAtCommit`.
+2. `git log lastPassCommit..regressedAtCommit -- <file>` shows the
+ commits that touched the affected file in the regression window.
+3. Inspect the diff for marker removal. Restore or update marker.
+
+## Anti-patterns to flag
+
+- Hand-edited `verification.md.json` (signature breaks; always re-regen).
+- A marker that's too generic (false-positives in unrelated code).
+- Committing the manifest without the history (or vice-versa).
+- Adding a fix entry whose `markerVerified=false` at issuance β€” fix the
+ build first, then regen.
+
+## In ruflo's CI
+
+`witness-verify` job in `v3-ci.yml` blocks `publish` if:
+- signature invalid (someone hand-edited the manifest)
+- any fix `regressed > 0` (a documented fix has lost its marker)
+- any fix `missing > 0` (a cited dist file doesn't exist)
+
+For users adopting the toolkit, a similar job in their own CI gates
+their own publishes the same way.
diff --git a/plugins/ruflo-core/commands/witness.md b/plugins/ruflo-core/commands/witness.md
new file mode 100644
index 0000000000..5d218fbbf3
--- /dev/null
+++ b/plugins/ruflo-core/commands/witness.md
@@ -0,0 +1,30 @@
+---
+name: witness
+description: Manage and verify a cryptographically-signed fix manifest with temporal history (ADR-103)
+argument-hint: "init|regen|verify|history|regressions [--manifest <path>] [--history <path>]"
+---
+
+$ARGUMENTS
+
+Run the appropriate witness sub-command. Defaults assume `verification.md.json` and `verification-history.jsonl` at the project root.
+
+```bash
+# Bootstrap (one-time per project)
+node plugins/ruflo-core/scripts/witness/init.mjs
+
+# Regen + append history (each release)
+node plugins/ruflo-core/scripts/witness/regen.mjs \
+ --manifest verification.md.json \
+ --history verification-history.jsonl \
+ --fixes witness-fixes.json
+
+# Verify against live tree
+node plugins/ruflo-core/scripts/witness/verify.mjs --manifest verification.md.json
+
+# Temporal queries
+node plugins/ruflo-core/scripts/witness/history.mjs --history verification-history.jsonl summary
+node plugins/ruflo-core/scripts/witness/history.mjs --history verification-history.jsonl regressions
+node plugins/ruflo-core/scripts/witness/history.mjs --history verification-history.jsonl timeline --id <fix-id>
+```
+
+See `plugins/ruflo-core/skills/witness/SKILL.md` for the full workflow + anti-patterns.
diff --git a/plugins/ruflo-core/scripts/witness/history.mjs b/plugins/ruflo-core/scripts/witness/history.mjs
new file mode 100644
index 0000000000..d73c1b682f
--- /dev/null
+++ b/plugins/ruflo-core/scripts/witness/history.mjs
@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+/**
+ * Query the witness temporal history (ADR-103).
+ *
+ * Usage:
+ * node history.mjs --history <path> <command> [--id <fixId>] [--json]
+ *
+ * Commands:
+ * summary Latest snapshot vs. previous (transitions in/out of pass).
+ * regressions For each currently-regressed fix, show the commit
+ * that introduced the regression (last pass β†’ first fail).
+ * timeline Status timeline for a single fix (--id required).
+ * list Show all snapshots (commit, issuedAt, summary).
+ *
+ * Options:
+ * --history <path> JSONL history file (defaults to ./verification-history.jsonl).
+ * --id <fixId> Fix id (e.g. F1, #1867) β€” required for `timeline`.
+ * --json Machine-readable output.
+ */
+
+import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { loadHistory, findRegressionIntroductions, fixTimeline, diffLatest } from './lib.mjs';
+
+const args = parseArgs(process.argv.slice(2));
+const cmd = args._[0];
+const historyPath = resolve(args.history ?? 'verification-history.jsonl');
+const asJson = !!args.json;
+
+if (!cmd || args.help) {
+ console.error('Usage: history.mjs --history <path> <summary|regressions|timeline|list> [--id X] [--json]');
+ process.exit(args.help ? 0 : 2);
+}
+
+if (!existsSync(historyPath)) {
+ if (asJson) console.log(JSON.stringify({ ok: false, error: `history file not found: ${historyPath}` }));
+ else console.error(`history file not found: ${historyPath}`);
+ process.exit(1);
+}
+
+const history = loadHistory(historyPath);
+
+if (cmd === 'list') {
+ if (asJson) {
+ console.log(JSON.stringify(history.map(e => ({ commit: e.commit, issuedAt: e.issuedAt, summary: e.summary })), null, 2));
+ } else {
+ for (const e of history) {
+ const s = e.summary;
+ console.log(`${e.issuedAt} ${e.commit.slice(0,12)} total=${s.totalFixes} verified=${s.verified} missing=${s.missing}`);
+ }
+ }
+ process.exit(0);
+}
+
+if (cmd === 'summary') {
+ const d = diffLatest(history);
+ const out = { entries: history.length, ...d };
+ if (asJson) console.log(JSON.stringify(out, null, 2));
+ else {
+ console.log(`history entries: ${history.length}`);
+ console.log(`newly regressed: ${d.newlyRegressed.length ? d.newlyRegressed.join(', ') : '(none)'}`);
+ console.log(`newly passing: ${d.newlyPassing.length ? d.newlyPassing.join(', ') : '(none)'}`);
+ console.log(`fixes added: ${d.added.length ? d.added.join(', ') : '(none)'}`);
+ console.log(`fixes removed: ${d.removed.length ? d.removed.join(', ') : '(none)'}`);
+ }
+ process.exit(d.newlyRegressed.length > 0 ? 1 : 0);
+}
+
+if (cmd === 'regressions') {
+ const r = findRegressionIntroductions(history);
+ if (asJson) console.log(JSON.stringify(r, null, 2));
+ else if (r.length === 0) console.log('no regressed fixes in latest snapshot');
+ else for (const x of r) {
+ console.log(`${x.id}`);
+ console.log(` last pass: ${x.lastPassCommit?.slice(0,12) ?? '(never)'} ${x.lastPassIssuedAt ?? ''}`);
+ console.log(` regressed at: ${x.regressedAtCommit.slice(0,12)} ${x.regressedAtIssuedAt}`);
+ }
+ process.exit(r.length > 0 ? 1 : 0);
+}
+
+if (cmd === 'timeline') {
+ if (!args.id) { console.error('--id <fixId> is required for timeline'); process.exit(2); }
+ const t = fixTimeline(history, args.id);
+ if (asJson) console.log(JSON.stringify(t, null, 2));
+ else for (const e of t) console.log(`${e.issuedAt} ${e.commit.slice(0,12)} ${e.status}`);
+ process.exit(0);
+}
+
+console.error(`unknown command: ${cmd}`);
+process.exit(2);
+
+function parseArgs(argv) {
+ const out = { _: [] };
+ for (let i = 0; i < argv.length; i++) {
+ const a = argv[i];
+ if (a === '--json' || a === '--help') { out[a.slice(2)] = true; continue; }
+ if (a.startsWith('--')) {
+ const key = a.slice(2);
+ const next = argv[i + 1];
+ if (next && !next.startsWith('--')) { out[key] = next; i++; }
+ else { out[key] = true; }
+ } else { out._.push(a); }
+ }
+ return out;
+}
diff --git a/plugins/ruflo-core/scripts/witness/init.mjs b/plugins/ruflo-core/scripts/witness/init.mjs
new file mode 100644
index 0000000000..7981606cca
--- /dev/null
+++ b/plugins/ruflo-core/scripts/witness/init.mjs
@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * Bootstrap a witness manifest in any project (ADR-103).
+ *
+ * Creates an empty `verification.md.json` and `verification-history.jsonl`
+ * at the project root, plus a stub `witness-fixes.json` template that
+ * users edit to register their own fix entries.
+ *
+ * Usage:
+ * node init.mjs [--root <path>]
+ */
+
+import { writeFileSync, existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+
+const args = parseArgs(process.argv.slice(2));
+const root = resolve(args.root ?? process.cwd());
+
+const manifestPath = join(root, 'verification.md.json');
+const historyPath = join(root, 'verification-history.jsonl');
+const fixesTemplate = join(root, 'witness-fixes.json');
+
+if (existsSync(manifestPath) && !args.force) {
+ console.error(`refusing to overwrite ${manifestPath} β€” pass --force to recreate`);
+ process.exit(1);
+}
+
+const emptyWitness = {
+ manifest: {
+ schema: 'ruflo-witness/v1',
+ issuedAt: new Date().toISOString(),
+ gitCommit: '',
+ branch: '',
+ releases: {},
+ summary: { totalFixes: 0, verified: 0, missing: 0 },
+ fixes: [],
+ },
+ integrity: {
+ manifestHashAlgo: 'sha256',
+ manifestHash: '',
+ signatureAlgo: 'ed25519',
+ publicKey: '',
+ signature: '',
+ seedDerivation: "sha256(gitCommit + ':ruflo-witness/v1')",
+ },
+};
+
+writeFileSync(manifestPath, JSON.stringify(emptyWitness, null, 2));
+writeFileSync(historyPath, '');
+writeFileSync(fixesTemplate, JSON.stringify({
+ fixes: [
+ {
+ id: 'EXAMPLE-1',
+ desc: 'Replace this with your fix description',
+ file: 'src/path/to/fixed-file.ts',
+ marker: 'distinctive substring proving the fix is in the file',
+ },
+ ],
+}, null, 2));
+
+console.log(`created:`);
+console.log(` ${manifestPath}`);
+console.log(` ${historyPath}`);
+console.log(` ${fixesTemplate} (edit then re-run regen)`);
+console.log(``);
+console.log(`next: install @noble/ed25519, edit witness-fixes.json, then:`);
+console.log(` node /path/to/regen.mjs --manifest verification.md.json \\`);
+console.log(` --history verification-history.jsonl \\`);
+console.log(` --fixes witness-fixes.json`);
+
+function parseArgs(argv) {
+ const out = {};
+ for (let i = 0; i < argv.length; i++) {
+ const a = argv[i];
+ if (a.startsWith('--')) {
+ const key = a.slice(2);
+ const next = argv[i + 1];
+ if (next && !next.startsWith('--')) { out[key] = next; i++; }
+ else { out[key] = true; }
+ }
+ }
+ return out;
+}
diff --git a/plugins/ruflo-core/scripts/witness/lib.mjs b/plugins/ruflo-core/scripts/witness/lib.mjs
new file mode 100644
index 0000000000..57c9bac496
--- /dev/null
+++ b/plugins/ruflo-core/scripts/witness/lib.mjs
@@ -0,0 +1,243 @@
+/**
+ * Witness library β€” shared logic for regenerating, verifying, and
+ * querying cryptographically-signed fix manifests with temporal
+ * history (ADR-103).
+ *
+ * Pure functions + small I/O helpers; no project-specific assumptions.
+ * CLI wrappers in this directory configure paths and surface output.
+ *
+ * @module plugins/ruflo-core/scripts/witness/lib
+ */
+
+import { readFileSync, writeFileSync, existsSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+
+// ─── ed25519 lazy load ─────────────────────────────────────────────
+// Locate @noble/ed25519 from the caller's project (it lives in their
+// node_modules, not bundled with this script). We probe a few likely
+// install roots so the toolkit works in ruflo's monorepo layout *and*
+// a user's flat node_modules.
+function loadEd25519(probeRoots) {
+ let lastErr;
+ for (const root of probeRoots) {
+ try {
+ const req = createRequire(join(root, 'noop.js'));
+ const ed = req('@noble/ed25519');
+ ed.etc.sha512Sync = (...m) => {
+ const h = createHash('sha512');
+ for (const x of m) h.update(x);
+ return h.digest();
+ };
+ return ed;
+ } catch (e) { lastErr = e; }
+ }
+ throw new Error(
+ "Could not locate '@noble/ed25519'. Install it in your project " +
+ "(npm i @noble/ed25519) or pass a node_modules root via the " +
+ "WITNESS_ED25519_ROOT env var. Last error: " + (lastErr?.message ?? '?')
+ );
+}
+
+// ─── manifest helpers ─────────────────────────────────────────────
+export function fileSha256(absPath) {
+ return createHash('sha256').update(readFileSync(absPath)).digest('hex');
+}
+
+export function fileContains(absPath, marker) {
+ return readFileSync(absPath, 'utf8').includes(marker);
+}
+
+export function refreshFix(repoRoot, fix) {
+ const abs = join(repoRoot, fix.file);
+ if (!existsSync(abs)) {
+ return { ...fix, sha256: fix.sha256 ?? '', markerVerified: false, _missing: true };
+ }
+ const sha256 = fileSha256(abs);
+ const markerVerified = fileContains(abs, fix.marker);
+ return { id: fix.id, desc: fix.desc, file: fix.file, sha256, marker: fix.marker, markerVerified };
+}
+
+// ─── regenerate ───────────────────────────────────────────────────
+/**
+ * Regenerate a signed witness manifest.
+ *
+ * @param {object} opts
+ * @param {string} opts.repoRoot Absolute path to the project root.
+ * @param {string} opts.manifestPath Where to write verification.md.json.
+ * @param {Array} opts.newFixes New fix entries to register.
+ * @param {object} [opts.releases] Map of pkg β†’ version for the manifest.
+ * @param {string[]} [opts.ed25519Roots] Probe roots for @noble/ed25519.
+ * @returns {{witness: object, summary: string}}
+ */
+export function regenerate(opts) {
+ const { repoRoot, manifestPath, newFixes = [], releases = {}, ed25519Roots = [] } = opts;
+ const ed = loadEd25519(ed25519Roots.length ? ed25519Roots : [repoRoot, join(repoRoot, 'v3')]);
+
+ const existing = existsSync(manifestPath) ? JSON.parse(readFileSync(manifestPath, 'utf8')) : null;
+ const oldFixes = existing?.manifest?.fixes ?? [];
+ const oldIds = new Set(oldFixes.map(f => f.id));
+
+ const merged = [
+ ...oldFixes.map(f => refreshFix(repoRoot, f)),
+ ...newFixes.filter(f => !oldIds.has(f.id)).map(f => refreshFix(repoRoot, f)),
+ ];
+
+ const gitCommit = execSync('git rev-parse HEAD', { cwd: repoRoot }).toString().trim();
+ const branch = execSync('git rev-parse --abbrev-ref HEAD', { cwd: repoRoot }).toString().trim();
+ const issuedAt = new Date().toISOString();
+
+ const verifiedCount = merged.filter(f => f.markerVerified).length;
+ const missingCount = merged.filter(f => f._missing).length;
+
+ const manifest = {
+ schema: existing?.manifest?.schema ?? 'ruflo-witness/v1',
+ issuedAt,
+ gitCommit,
+ branch,
+ releases,
+ summary: { totalFixes: merged.length, verified: verifiedCount, missing: missingCount },
+ fixes: merged.map(f => { const { _missing, ...c } = f; return c; }),
+ };
+
+ const manifestCanonical = JSON.stringify(manifest);
+ const manifestHash = createHash('sha256').update(manifestCanonical).digest('hex');
+ const seed = createHash('sha256').update(gitCommit + ':ruflo-witness/v1').digest();
+ const publicKey = ed.getPublicKey(seed);
+ const signature = ed.sign(Buffer.from(manifestHash, 'hex'), seed);
+
+ const witness = {
+ manifest,
+ integrity: {
+ manifestHashAlgo: 'sha256',
+ manifestHash,
+ signatureAlgo: 'ed25519',
+ publicKey: Buffer.from(publicKey).toString('hex'),
+ signature: Buffer.from(signature).toString('hex'),
+ seedDerivation: "sha256(gitCommit + ':ruflo-witness/v1')",
+ },
+ };
+
+ const newIds = newFixes.filter(f => !oldIds.has(f.id)).map(f => f.id);
+ const summary =
+ `gitCommit: ${gitCommit.slice(0,12)}…\n` +
+ `branch: ${branch}\n` +
+ `issuedAt: ${issuedAt}\n` +
+ `total fixes: ${merged.length} (was ${oldFixes.length})\n` +
+ `verified: ${verifiedCount}\n` +
+ `missing: ${missingCount}\n` +
+ `new entries: ${newIds.join(', ') || '(none)'}\n` +
+ `releases: ${JSON.stringify(releases)}`;
+
+ return { witness, summary, manifest, gitCommit, manifestHash };
+}
+
+// ─── temporal history ─────────────────────────────────────────────
+/**
+ * Append a compact snapshot of `manifest` to a JSONL history file.
+ * One line per regen β€” git-diff-friendly, append-cheap.
+ *
+ * @param {string} historyPath Path to verification-history.jsonl.
+ * @param {object} manifest The manifest object just signed.
+ * @param {string} manifestHash The signed hash (for fast lookup).
+ */
+export function appendHistory(historyPath, manifest, manifestHash) {
+ const fixesIndex = {};
+ for (const f of manifest.fixes) {
+ fixesIndex[f.id] = { sha256: f.sha256, markerVerified: f.markerVerified };
+ }
+ const entry = {
+ v: 1,
+ commit: manifest.gitCommit,
+ issuedAt: manifest.issuedAt,
+ branch: manifest.branch,
+ manifestHash,
+ summary: manifest.summary,
+ fixes: fixesIndex,
+ };
+ appendFileSync(historyPath, JSON.stringify(entry) + '\n');
+ return entry;
+}
+
+/**
+ * Load the JSONL history into memory (one entry per line).
+ */
+export function loadHistory(historyPath) {
+ if (!existsSync(historyPath)) return [];
+ const lines = readFileSync(historyPath, 'utf8').split('\n').filter(Boolean);
+ return lines.map(l => JSON.parse(l));
+}
+
+/**
+ * For each fix that is currently `regressed` (markerVerified=false in the
+ * latest entry), walk backwards to find the most recent entry where it
+ * was `pass` (markerVerified=true). The next entry after that is where
+ * the regression was introduced.
+ *
+ * @returns {Array<{id, lastPassCommit, regressedAtCommit, atIssuedAt}>}
+ */
+export function findRegressionIntroductions(history) {
+ if (history.length === 0) return [];
+ const latest = history[history.length - 1];
+ const out = [];
+ for (const [id, state] of Object.entries(latest.fixes)) {
+ if (state.markerVerified) continue;
+ let lastPass = null;
+ let regressedAt = latest;
+ for (let i = history.length - 2; i >= 0; i--) {
+ const e = history[i];
+ const s = e.fixes[id];
+ if (s && s.markerVerified) { lastPass = e; break; }
+ regressedAt = e;
+ }
+ out.push({
+ id,
+ lastPassCommit: lastPass?.commit ?? null,
+ lastPassIssuedAt: lastPass?.issuedAt ?? null,
+ regressedAtCommit: regressedAt.commit,
+ regressedAtIssuedAt: regressedAt.issuedAt,
+ });
+ }
+ return out;
+}
+
+/**
+ * Build a status timeline for a single fix across all history entries.
+ *
+ * @returns {Array<{commit, issuedAt, status}>}
+ * status ∈ { 'pass', 'regressed', 'absent' }
+ */
+export function fixTimeline(history, fixId) {
+ return history.map(e => ({
+ commit: e.commit,
+ issuedAt: e.issuedAt,
+ status: e.fixes[fixId]
+ ? (e.fixes[fixId].markerVerified ? 'pass' : 'regressed')
+ : 'absent',
+ }));
+}
+
+/**
+ * Compare the latest entry to the previous entry and report transitions.
+ *
+ * @returns {{newlyRegressed: string[], newlyPassing: string[], added: string[], removed: string[]}}
+ */
+export function diffLatest(history) {
+ if (history.length < 2) return { newlyRegressed: [], newlyPassing: [], added: [], removed: [] };
+ const [prev, curr] = [history[history.length - 2], history[history.length - 1]];
+ const newlyRegressed = [];
+ const newlyPassing = [];
+ const added = [];
+ const removed = [];
+ for (const id of Object.keys(curr.fixes)) {
+ if (!(id in prev.fixes)) added.push(id);
+ else if (prev.fixes[id].markerVerified && !curr.fixes[id].markerVerified) newlyRegressed.push(id);
+ else if (!prev.fixes[id].markerVerified && curr.fixes[id].markerVerified) newlyPassing.push(id);
+ }
+ for (const id of Object.keys(prev.fixes)) {
+ if (!(id in curr.fixes)) removed.push(id);
+ }
+ return { newlyRegressed, newlyPassing, added, removed };
+}
diff --git a/plugins/ruflo-core/scripts/witness/regen.mjs b/plugins/ruflo-core/scripts/witness/regen.mjs
new file mode 100644
index 0000000000..d19d8e5568
--- /dev/null
+++ b/plugins/ruflo-core/scripts/witness/regen.mjs
@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/**
+ * Regenerate a signed witness manifest with temporal history (ADR-103).
+ *
+ * Project-agnostic CLI wrapper around `lib.mjs`. Works in any repo that
+ * has @noble/ed25519 installed somewhere (this script probes common roots).
+ *
+ * Usage:
+ * node regen.mjs --manifest <path> [--history <path>] [--fixes <json>] [--dry-run]
+ *
+ * Options:
+ * --manifest <path> Where to write the signed manifest (verification.md.json).
+ * --history <path> JSONL history file to append a snapshot (omit to skip).
+ * --fixes <path> JSON file with NEW_FIXES to register on this regen.
+ * Format: { "fixes": [ { "id", "desc", "file", "marker" }, ... ] }
+ * --releases <path> Optional JSON file mapping pkg β†’ version for the manifest.
+ * --root <path> Project root (defaults to cwd).
+ * --dry-run Print summary without writing.
+ *
+ * Examples:
+ * # Refresh existing manifest (no new fixes)
+ * node regen.mjs --manifest verification.md.json --history verification-history.jsonl
+ *
+ * # Add new fixes from a config file
+ * node regen.mjs --manifest verification.md.json --history verification-history.jsonl \
+ * --fixes new-fixes.json --releases releases.json
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { regenerate, appendHistory } from './lib.mjs';
+
+const args = parseArgs(process.argv.slice(2));
+if (!args.manifest) {
+ console.error('Error: --manifest <path> is required');
+ console.error('Run with --help for usage.');
+ process.exit(2);
+}
+if (args.help) {
+ console.log(readFileSync(new URL(import.meta.url), 'utf8').split('\n').filter(l => l.startsWith(' *')).map(l => l.slice(3)).join('\n'));
+ process.exit(0);
+}
+
+const repoRoot = resolve(args.root ?? process.cwd());
+const manifestPath = resolve(args.manifest);
+const historyPath = args.history ? resolve(args.history) : null;
+
+const newFixes = args.fixes
+ ? JSON.parse(readFileSync(resolve(args.fixes), 'utf8')).fixes ?? []
+ : [];
+
+const releases = args.releases
+ ? JSON.parse(readFileSync(resolve(args.releases), 'utf8'))
+ : {};
+
+const result = regenerate({
+ repoRoot,
+ manifestPath,
+ newFixes,
+ releases,
+ ed25519Roots: [repoRoot, resolve(repoRoot, 'v3')],
+});
+
+console.log(`witness regen summary\n─────────────────────`);
+console.log(result.summary);
+
+if (args['dry-run']) {
+ console.log('\n(dry-run β€” manifest NOT written)');
+ process.exit(0);
+}
+
+writeFileSync(manifestPath, JSON.stringify(result.witness, null, 2));
+console.log(`\nwritten: ${manifestPath}`);
+
+if (historyPath) {
+ appendHistory(historyPath, result.witness.manifest, result.manifestHash);
+ console.log(`appended: ${historyPath}`);
+}
+
+// ─── tiny arg parser (no deps) ────────────────────────────────────
+function parseArgs(argv) {
+ const out = {};
+ for (let i = 0; i < argv.length; i++) {
+ const a = argv[i];
+ if (a === '--dry-run' || a === '--help') { out[a.slice(2)] = true; continue; }
+ if (a.startsWith('--')) {
+ const key = a.slice(2);
+ const next = argv[i + 1];
+ if (next && !next.startsWith('--')) { out[key] = next; i++; }
+ else { out[key] = true; }
+ }
+ }
+ return out;
+}
diff --git a/plugins/ruflo-core/scripts/witness/verify.mjs b/plugins/ruflo-core/scripts/witness/verify.mjs
new file mode 100644
index 0000000000..cf87a8f4b9
--- /dev/null
+++ b/plugins/ruflo-core/scripts/witness/verify.mjs
@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+/**
+ * Verify a signed witness manifest against the live tree (ADR-103).
+ *
+ * Project-agnostic β€” works without ruflo CLI being installed.
+ *
+ * Usage:
+ * node verify.mjs --manifest <path> [--root <path>] [--json]
+ *
+ * Exit codes:
+ * 0 β€” signature valid + all fixes pass or drift (marker present)
+ * 1 β€” signature invalid OR any fix regressed/missing
+ * 2 β€” bad arguments / file not found
+ */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve, join, sep } from 'node:path';
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { fileSha256, fileContains } from './lib.mjs';
+
+const args = parseArgs(process.argv.slice(2));
+if (!args.manifest) { console.error('--manifest <path> required'); process.exit(2); }
+
+const manifestPath = resolve(args.manifest);
+if (!existsSync(manifestPath)) { console.error(`not found: ${manifestPath}`); process.exit(2); }
+
+const repoRoot = resolve(args.root ?? process.cwd());
+const asJson = !!args.json;
+
+const witness = JSON.parse(readFileSync(manifestPath, 'utf8'));
+
+// ─── signature ────────────────────────────────────────────────────
+const sig = await verifySignature(witness, repoRoot);
+
+// ─── per-fix marker check ─────────────────────────────────────────
+const fileResults = witness.manifest.fixes.map((fix) => {
+ const installed = join(repoRoot, fix.file);
+ if (!existsSync(installed)) {
+ return { ...fix, status: 'missing', sha256Match: false, markerPresent: false };
+ }
+ const localSha256 = fileSha256(installed);
+ const markerPresent = fileContains(installed, fix.marker);
+ const sha256Match = localSha256 === fix.sha256;
+ const status = sha256Match && markerPresent ? 'pass'
+ : (markerPresent ? 'drift' : 'regressed');
+ return { ...fix, status, sha256Match, markerPresent, localSha256 };
+});
+
+const summary = {
+ pass: fileResults.filter(r => r.status === 'pass').length,
+ drift: fileResults.filter(r => r.status === 'drift').length,
+ regressed: fileResults.filter(r => r.status === 'regressed').length,
+ missing: fileResults.filter(r => r.status === 'missing').length,
+};
+const ok = sig.signatureValid && sig.manifestHashOk && sig.publicKeyReproducible
+ && summary.regressed === 0 && summary.missing === 0;
+
+if (asJson) {
+ console.log(JSON.stringify({ ok, signature: sig, summary, results: fileResults }, null, 2));
+} else {
+ console.log('Manifest signature:');
+ console.log(` hash matches: ${sig.manifestHashOk ? 'yes' : 'NO'}`);
+ console.log(` public key reproducible: ${sig.publicKeyReproducible ? 'yes' : 'NO'}`);
+ console.log(` Ed25519 signature valid: ${sig.signatureValid ? 'yes' : 'NO'}`);
+ console.log('');
+ console.log(`Summary: pass=${summary.pass} drift=${summary.drift} regressed=${summary.regressed} missing=${summary.missing}`);
+ if (summary.regressed > 0) {
+ console.log('\nRegressed:');
+ for (const r of fileResults.filter(r => r.status === 'regressed')) {
+ console.log(` ${r.id} marker missing in ${r.file}`);
+ }
+ }
+ if (summary.missing > 0) {
+ console.log('\nMissing files:');
+ for (const r of fileResults.filter(r => r.status === 'missing')) {
+ console.log(` ${r.id} ${r.file}`);
+ }
+ }
+}
+
+process.exit(ok ? 0 : 1);
+
+// ─── ed25519 helpers ─────────────────────────────────────────────
+async function verifySignature(witness, repoRoot) {
+ let ed;
+ for (const root of [repoRoot, join(repoRoot, 'v3')]) {
+ try { ed = createRequire(join(root, 'noop.js'))('@noble/ed25519'); break; } catch { /* try next */ }
+ }
+ if (!ed) return { manifestHashOk: false, publicKeyReproducible: false, signatureValid: false };
+
+ ed.etc.sha512Sync = (...m) => { const h = createHash('sha512'); for (const x of m) h.update(x); return h.digest(); };
+
+ const recomputed = createHash('sha256').update(JSON.stringify(witness.manifest)).digest('hex');
+ const manifestHashOk = recomputed === witness.integrity.manifestHash;
+ const seed = createHash('sha256').update(witness.manifest.gitCommit + ':ruflo-witness/v1').digest();
+ const reKey = ed.getPublicKey(seed);
+ const publicKeyReproducible = Buffer.from(reKey).toString('hex') === witness.integrity.publicKey;
+ const signatureValid = ed.verify(
+ Buffer.from(witness.integrity.signature, 'hex'),
+ Buffer.from(witness.integrity.manifestHash, 'hex'),
+ Buffer.from(witness.integrity.publicKey, 'hex'),
+ );
+ return { manifestHashOk, publicKeyReproducible, signatureValid };
+}
+
+function parseArgs(argv) {
+ const out = {};
+ for (let i = 0; i < argv.length; i++) {
+ const a = argv[i];
+ if (a === '--json' || a === '--help') { out[a.slice(2)] = true; continue; }
+ if (a.startsWith('--')) {
+ const key = a.slice(2);
+ const next = argv[i + 1];
+ if (next && !next.startsWith('--')) { out[key] = next; i++; }
+ else { out[key] = true; }
+ }
+ }
+ return out;
+}
diff --git a/plugins/ruflo-core/skills/witness/SKILL.md b/plugins/ruflo-core/skills/witness/SKILL.md
new file mode 100644
index 0000000000..16d231b2cc
--- /dev/null
+++ b/plugins/ruflo-core/skills/witness/SKILL.md
@@ -0,0 +1,102 @@
+---
+name: witness
+description: Sign, verify, and track fix-marker regressions over time using a deterministic Ed25519 witness manifest. Works in any project β€” clone the toolkit, run init, register fixes, regen on each release.
+argument-hint: "init|regen|verify|history [...]"
+allowed-tools: Bash(node *), Read, Write, Edit
+---
+
+# 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)
+
+```bash
+# 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.json
+```
+
+## Temporal queries (ADR-103)
+
+```bash
+# 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:
+
+| 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 |
diff --git a/scripts/regen-witness.mjs b/scripts/regen-witness.mjs
index 89ef56f8cb..1c70c0ea9c 100644
--- a/scripts/regen-witness.mjs
+++ b/scripts/regen-witness.mjs
@@ -1,114 +1,31 @@
#!/usr/bin/env node
/**
- * Regenerate the cryptographically-signed witness manifest at
- * `verification.md.json` for the current git HEAD.
+ * ruflo-internal witness regen β€” thin wrapper around the canonical
+ * implementation in `plugins/ruflo-core/scripts/witness/regen.mjs`.
*
- * Used after publishing a release with new fix entries. Replaces the
- * inline regen described in `~/.claude/.../project_verification_process.md`.
- *
- * Behavior:
- * 1. Loads the existing manifest's `fixes[]` (so prior 78 entries persist).
- * 2. Appends entries from NEW_FIXES below.
- * 3. Refreshes each fix's sha256 against the current dist; sets
- * `markerVerified` based on whether the marker substring is present.
- * 4. Updates `issuedAt`, `gitCommit`, `branch`, `releases`, and `summary`.
- * 5. Computes manifest hash, derives Ed25519 keypair from
- * `sha256(gitCommit + ':ruflo-witness/v1')`, signs the manifest hash.
- * 6. Writes verification.md.json.
+ * The plugin script is project-agnostic; this wrapper hard-codes ruflo's
+ * paths so contributors can run a one-liner. Add new fix entries by
+ * editing `witness-fixes.json` at the repo root.
*
* Usage:
- * node scripts/regen-witness.mjs # regen using current HEAD
- * node scripts/regen-witness.mjs --dry-run # print what would change
- *
- * To register a new fix, append a `{ id, desc, file, marker }` entry to
- * NEW_FIXES. The script computes sha256 + markerVerified at write time.
+ * node scripts/regen-witness.mjs # regen + append history
+ * node scripts/regen-witness.mjs --dry-run # preview without writing
*/
import { readFileSync, writeFileSync, existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { execSync } from 'node:child_process';
-import { createHash } from 'node:crypto';
-import { createRequire } from 'node:module';
-
-// `@noble/ed25519` is installed in the `v3/` workspace, not at repo root.
-// Use createRequire so the script runs without a top-level `npm install`.
-const require = createRequire(join(process.cwd(), 'v3/node_modules/.placeholder'));
-const ed = require('@noble/ed25519');
-
-ed.etc.sha512Sync = (...m) => {
- const h = createHash('sha512');
- for (const x of m) h.update(x);
- return h.digest();
-};
+import { join, resolve } from 'node:path';
+import { regenerate, appendHistory } from '../plugins/ruflo-core/scripts/witness/lib.mjs';
const REPO_ROOT = process.cwd();
const MANIFEST_PATH = join(REPO_ROOT, 'verification.md.json');
+const HISTORY_PATH = join(REPO_ROOT, 'verification-history.jsonl');
+const FIXES_CONFIG = join(REPO_ROOT, 'witness-fixes.json');
const DRY_RUN = process.argv.includes('--dry-run');
-// New fix entries to register on this regen. The script will compute
-// sha256 + markerVerified for each. Append entries here when shipping
-// a release with new documented fixes.
-const NEW_FIXES = [
- {
- id: '#1867',
- desc: 'Node 26 install: better-sqlite3 dynamic import + optionalDependencies',
- file: 'v3/@claude-flow/memory/dist/sqlite-backend.js',
- marker: "(await import('better-sqlite3')).default",
- },
- {
- id: '#1859',
- desc: 'CLI flag/positional priority swap β€” named flags win over stray positionals (14 sites in hooks.ts)',
- file: 'v3/@claude-flow/cli/dist/src/commands/hooks.js',
- marker: 'ctx.flags.file || ctx.args[0]',
- },
- {
- id: '#1862',
- desc: 'ruflo-core PostToolUse hooks call documented CLI flags (-c/-s/-e, -f/-s) instead of bogus --format true',
- file: 'plugins/ruflo-core/hooks/hooks.json',
- marker: 'hooks post-edit -f \\"$FILE\\" -s true',
- },
-];
-
-// ─────────────────────────────────────────────────────────────────────
-
-function readJson(path) {
- return JSON.parse(readFileSync(path, 'utf8'));
-}
-
-function fileSha256(absPath) {
- return createHash('sha256').update(readFileSync(absPath)).digest('hex');
-}
-
-function fileContains(absPath, marker) {
- return readFileSync(absPath, 'utf8').includes(marker);
-}
+const newFixes = existsSync(FIXES_CONFIG)
+ ? JSON.parse(readFileSync(FIXES_CONFIG, 'utf8')).fixes ?? []
+ : [];
-function refreshFix(fix) {
- const abs = join(REPO_ROOT, fix.file);
- if (!existsSync(abs)) {
- return { ...fix, sha256: fix.sha256 ?? '', markerVerified: false, _missing: true };
- }
- const sha256 = fileSha256(abs);
- const markerVerified = fileContains(abs, fix.marker);
- return { id: fix.id, desc: fix.desc, file: fix.file, sha256, marker: fix.marker, markerVerified };
-}
-
-// ─────────────────────────────────────────────────────────────────────
-
-const witness = readJson(MANIFEST_PATH);
-const oldFixes = witness.manifest?.fixes ?? [];
-const oldIds = new Set(oldFixes.map(f => f.id));
-
-const merged = [
- ...oldFixes.map(refreshFix),
- ...NEW_FIXES.filter(f => !oldIds.has(f.id)).map(refreshFix),
-];
-
-const gitCommit = execSync('git rev-parse HEAD', { cwd: REPO_ROOT }).toString().trim();
-const branch = execSync('git rev-parse --abbrev-ref HEAD', { cwd: REPO_ROOT }).toString().trim();
-const issuedAt = new Date().toISOString();
-
-// Read package versions for the releases block.
const releases = {};
for (const [key, pkgPath] of [
['ruflo', 'ruflo/package.json'],
@@ -117,71 +34,28 @@ for (const [key, pkgPath] of [
['@claude-flow/memory', 'v3/@claude-flow/memory/package.json'],
]) {
const fullPath = join(REPO_ROOT, pkgPath);
- if (existsSync(fullPath)) {
- releases[key] = readJson(fullPath).version;
- }
+ if (existsSync(fullPath)) releases[key] = JSON.parse(readFileSync(fullPath, 'utf8')).version;
}
-const verifiedCount = merged.filter(f => f.markerVerified).length;
-const missingCount = merged.filter(f => f._missing).length;
-
-const manifest = {
- schema: witness.manifest?.schema ?? 'ruflo-witness/v1',
- issuedAt,
- gitCommit,
- branch,
+const result = regenerate({
+ repoRoot: REPO_ROOT,
+ manifestPath: MANIFEST_PATH,
+ newFixes,
releases,
- summary: {
- totalFixes: merged.length,
- verified: verifiedCount,
- missing: missingCount,
- },
- fixes: merged.map(f => {
- // Strip internal-only fields before signing.
- const { _missing: _drop, ...clean } = f;
- return clean;
- }),
-};
-
-const manifestCanonical = JSON.stringify(manifest);
-const manifestHash = createHash('sha256').update(manifestCanonical).digest('hex');
-const seed = createHash('sha256').update(gitCommit + ':ruflo-witness/v1').digest();
-// @noble/ed25519 v2 exposes both sync and async APIs; sync is fine here
-// because we configured sha512Sync above.
-const publicKey = ed.getPublicKey(seed);
-const signature = ed.sign(Buffer.from(manifestHash, 'hex'), seed);
+ ed25519Roots: [REPO_ROOT, join(REPO_ROOT, 'v3')],
+});
-const fullWitness = {
- manifest,
- integrity: {
- manifestHashAlgo: 'sha256',
- manifestHash,
- signatureAlgo: 'ed25519',
- publicKey: Buffer.from(publicKey).toString('hex'),
- signature: Buffer.from(signature).toString('hex'),
- seedDerivation: "sha256(gitCommit + ':ruflo-witness/v1')",
- },
-};
-
-const summary = `
-witness regen summary
-─────────────────────
- gitCommit: ${gitCommit.slice(0, 12)}…
- branch: ${branch}
- issuedAt: ${issuedAt}
- total fixes: ${manifest.summary.totalFixes} (was ${oldFixes.length})
- verified: ${verifiedCount}
- missing: ${missingCount}
- new entries: ${NEW_FIXES.filter(f => !oldIds.has(f.id)).map(f => f.id).join(', ') || '(none)'}
- releases: ${JSON.stringify(releases)}
-`;
+console.log('witness regen summary');
+console.log('─────────────────────');
+console.log(result.summary);
if (DRY_RUN) {
- console.log(summary);
- console.log('(dry-run β€” manifest NOT written)');
+ console.log('\n(dry-run β€” manifest NOT written)');
process.exit(0);
}
-writeFileSync(MANIFEST_PATH, JSON.stringify(fullWitness, null, 2));
-console.log(summary);
-console.log(`written: ${MANIFEST_PATH}`);
+writeFileSync(MANIFEST_PATH, JSON.stringify(result.witness, null, 2));
+console.log(`\nwritten: ${MANIFEST_PATH}`);
+
+appendHistory(HISTORY_PATH, result.witness.manifest, result.manifestHash);
+console.log(`appended: ${HISTORY_PATH}`);
diff --git a/v3/docs/adr/ADR-103-witness-temporal-history.md b/v3/docs/adr/ADR-103-witness-temporal-history.md
new file mode 100644
index 0000000000..647462294e
--- /dev/null
+++ b/v3/docs/adr/ADR-103-witness-temporal-history.md
@@ -0,0 +1,172 @@
+# ADR-103: Witness Temporal History + Plugin-Distributed Toolkit
+
+**Status**: Accepted
+**Date**: 2026-05-08
+**Version**: [email protected]+ / @claude-flow/[email protected]+
+**Related**: ADR-102 (CI smoke harness), #1867, #1859, #1862, project memory `project_verification_process.md`
+
+## Context
+
+The signed witness manifest at `verification.md.json` (described in
+`verification.md`) attests that every documented fix in the codebase is
+still present, by SHA-256 + marker substring, signed Ed25519 with a
+deterministic seed derived from the git commit.
+
+It works well as a snapshot, but has two structural gaps:
+
+### Gap 1 β€” No temporal data
+
+The manifest is overwritten every regen. A fix that flips `pass β†’ drift β†’
+regressed` carries no history. When CI says "F12 is regressed", you can
+only answer "as of HEAD, marker is missing" β€” not "introduced between
+commit X and Y, on date D, in PR #N". For a project with 80+ tracked
+fixes across rapid alpha churn, this turns regression triage into a
+manual git-bisect every time.
+
+### Gap 2 β€” Toolkit is ruflo-internal
+
+The regen logic was originally inline in shell heredocs (per the
+`project_verification_process.md` memory) and later extracted to
+`scripts/regen-witness.mjs`. Both forms hard-code ruflo's paths and
+fix list. Other projects can't adopt the witness pattern without
+copy-pasting and rewriting. Given that several downstream consumers
+of `ruflo` and `@claude-flow/cli` ship their own fixes, this is a
+real adoption blocker.
+
+## Decision
+
+### 1. Append-only JSONL temporal history
+
+Each regen appends one line to `verification-history.jsonl`:
+
+```jsonc
+{
+ "v": 1,
+ "commit": "<gitCommit at issuance>",
+ "issuedAt": "<ISO timestamp>",
+ "branch": "<branch>",
+ "manifestHash": "<sha256 of canonical manifest>",
+ "summary": { "totalFixes": N, "verified": M, "missing": K },
+ "fixes": {
+ "F1": { "sha256": "...", "markerVerified": true },
+ "#1867":{ "sha256": "...", "markerVerified": true },
+ /* ... one entry per fix, keyed by id ... */
+ }
+}
+```
+
+Format choice: JSONL because
+
+- Append is atomic and cheap (no rewrite of prior lines).
+- Git diffs are minimal β€” one new line per regen.
+- Trivially parsable from any tool without binary format support.
+- Matches the project's existing convention (`pending-insights.jsonl`).
+
+The file is committed alongside `verification.md.json`. They must move
+as a pair β€” the manifest is the latest signed snapshot, the JSONL is
+the timeline that proves it's the latest.
+
+### 2. Ship the toolkit as a `ruflo-core` plugin asset
+
+The witness scripts move to `plugins/ruflo-core/scripts/witness/`:
+
+| File | Purpose |
+|---|---|
+| `lib.mjs` | Pure functions: `regenerate`, `appendHistory`, `loadHistory`, `findRegressionIntroductions`, `fixTimeline`, `diffLatest` |
+| `init.mjs` | Bootstrap empty manifest + history + fix template into any repo |
+| `regen.mjs` | Sign the manifest + append history (the canonical workflow) |
+| `verify.mjs` | Validate signature + markers against the live tree |
+| `history.mjs` | Query the temporal log: `summary`, `regressions`, `timeline`, `list` |
+
+Plus exposure as Claude Code surface area:
+
+| File | Purpose |
+|---|---|
+| `plugins/ruflo-core/skills/witness/SKILL.md` | Workflow doc + anti-patterns |
+| `plugins/ruflo-core/commands/witness.md` | Slash-command thin wrapper |
+| `plugins/ruflo-core/agents/witness-curator.md` | Agent for adding fixes / interpreting regressions |
+
+The scripts are project-agnostic: they take `--manifest`, `--history`,
+`--fixes`, `--root` flags. They probe `<root>` and `<root>/v3` for
+`@noble/ed25519`, so they work in monorepo and flat layouts.
+
+The ruflo internal entrypoint at `scripts/regen-witness.mjs` is now a
+thin wrapper that hard-codes ruflo's paths and reads the
+project-specific fix list from `witness-fixes.json`. Single source of
+truth lives in the plugin.
+
+### 3. CI integration
+
+The `witness-verify` job in `.github/workflows/v3-ci.yml` (added by
+ADR-102 Β§3) gains a follow-on step that runs `history.mjs summary`
+to surface transitions since the previous snapshot. The summary
+subcommand exits non-zero on any newly-regressed fix β€” informational
+in the current pipeline, but adopters can promote it to a hard gate
+in their own CI.
+
+### 4. Regression-introduction queries
+
+`history.mjs regressions` walks the JSONL backwards to find, for each
+currently-regressed fix, the most recent snapshot where it was passing
+(`lastPassCommit`). The next snapshot's commit (`regressedAtCommit`)
+brackets the regression to a single window. Combined with `git log
+lastPassCommit..regressedAtCommit -- <file>`, this collapses bisect
+to a small set of commits to read.
+
+## Implementation notes
+
+- `appendHistory` strips the manifest's `desc`/`marker`/`file` fields
+ from the per-fix record. Those don't change frequently and would
+ bloat the JSONL. If a marker is updated mid-stream, the JSONL still
+ records the SHA-256 + verified-status pair from each regen, which is
+ the load-bearing signal for regression detection.
+- The JSONL keeps fixes keyed by id (object), not array. This makes
+ per-fix lookups O(1) without scanning, which matters once history
+ reaches 100+ entries.
+- `verify.mjs` is parallel to the bundled `ruflo verify` command but
+ has no ruflo CLI dependency β€” adopters who only want the witness
+ toolkit can install one tiny package (`@noble/ed25519`) and run it.
+
+## Consequences
+
+### Capabilities gained
+
+- Regression introduction time becomes a one-command answer.
+- Per-fix status timelines for trend analysis (which fixes flap, which
+ drift consistently, which regress permanently).
+- Other projects can adopt the witness pattern by copying
+ `plugins/ruflo-core/scripts/witness/` and `init`-ing β€” no ruflo
+ install required.
+- The CI surface gains a soft gate that highlights *what* regressed,
+ not just *that* something regressed.
+
+### Costs
+
+- One extra file in the repo (`verification-history.jsonl`).
+- ~2-3 KB per regen entry (81 fixes Γ— ~30 bytes avg). After 1000
+ regens, ~3 MB.
+- Adopters take a runtime dependency on `@noble/ed25519` (~15 KB
+ minified, no transitive deps).
+
+### Not addressed (residual)
+
+- No vector-graph similarity over snapshots. The user's original
+ question floated `/ruvector` as a substrate. JSONL is sufficient for
+ the queries we need today; an HNSW-backed similarity index over
+ snapshot fingerprints is a follow-up if pattern-based queries
+ ("snapshots most similar to commit X") become valuable.
+- No cross-project history aggregation. Each project's JSONL is local.
+ Multi-project rollups would need a separate ingestion service.
+- The `verify.mjs` script duplicates a small amount of logic with
+ `v3/@claude-flow/cli/src/commands/verify.ts`. Acceptable for now
+ (the standalone needs to work without the CLI installed); could be
+ unified later if both move to the plugin.
+
+## References
+
+- `plugins/ruflo-core/skills/witness/SKILL.md` β€” adoption guide
+- `plugins/ruflo-core/agents/witness-curator.md` β€” agent definition
+- `~/.claude/.../project_verification_process.md` β€” original inline
+ regen process; superseded by this ADR's plugin-extracted form
+- ADR-102 β€” CI smoke harness pattern (this ADR generalizes the
+ smoke-test layer to a fully temporal verification layer)
diff --git a/verification-history.jsonl b/verification-history.jsonl
new file mode 100644
index 0000000000..f098d32896
--- /dev/null
+++ b/verification-history.jsonl
@@ -0,0 +1 @@
+{"v":1,"commit":"54c706f561389888941f5b107bb7e2deea3b076d","issuedAt":"2026-05-09T01:00:47.879Z","branch":"main","manifestHash":"0fb659a57aa21426ab98e8e70fd0ce46bf082afb9b4f5bb710a81d7a19997c24","summary":{"totalFixes":81,"verified":81,"missing":0},"fixes":{"F1":{"sha256":"4c255b1d1ac66655551d6c199395f3174cde09f3012e5283f26eb402e7961cac","markerVerified":true},"F2":{"sha256":"4c255b1d1ac66655551d6c199395f3174cde09f3012e5283f26eb402e7961cac","markerVerified":true},"F3":{"sha256":"6987df2e11f6c5fe7cb2a4f5b2ba8c883a6705b447b3c0d0f237a2187e5e28a4","markerVerified":true},"F4":{"sha256":"6ca2c3b6d17e39378a6d95b9ef104a4c7e01c321687a4e21fc5ddc599589f91f","markerVerified":true},"F5":{"sha256":"6f0f172840b7db1a491356bed5f7b6b6f6e8760633cd38e1bc968f4aa22bc946","markerVerified":true},"F6":{"sha256":"f623493c80bd305bbf9bf426563db5a9ad745817972bc5690c84a1d1b33e92b9","markerVerified":true},"F7":{"sha256":"5d9b47750015c4626b044453494ef9905ccda9cbb35a06f56215783b6251cef0","markerVerified":true},"F8":{"sha256":"d612f3c006c7c1bf3283c0c257bc24557feff65f8b1f3dbb32c4b9a33478767c","markerVerified":true},"F9":{"sha256":"12ca47650a812c66fb5efbbc3b6cdf527ca74ee787f27c9556514492de9d07cd","markerVerified":true},"F10":{"sha256":"4c255b1d1ac66655551d6c199395f3174cde09f3012e5283f26eb402e7961cac","markerVerified":true},"F11":{"sha256":"7e08b72ac68774af172107f93aba27c5e7254bdb52ba6a8a686da7917fe81e9b","markerVerified":true},"F12":{"sha256":"811ac1297fea330f0e497523a234eb97339a4e1c009b2c33be14915b662b7dec","markerVerified":true},"#1697":{"sha256":"9c9233e068f02511a4c8c310640fc0d3285b449435df5819afa9cc8ac211ff42","markerVerified":true},"#1698":{"sha256":"2cb57b6fb38bb4722eebd169f4b6056f1b6f69ba0adde9978bcd9e03f83d43ab","markerVerified":true},"#1691":{"sha256":"8fe7b53ad914532474b77cf419b6e64ee60e12562062342e9cf9fd5eee8c8498","markerVerified":true},"#1721":{"sha256":"b6836a525ba4914a9e9a42116bbdbb56449c3505a203611891e21888cc84ac4b","markerVerified":true},"ADR-094":{"sha256":"1d2225e7422f8a2d47d39100324d5e4ac2d29c55e8e72b02f5e4a7a113d45be2","markerVerified":true},"G1":{"sha256":"3070ca38954ad68385faf54d4111e7395cf0667a3f4db6607fe1b9b3d84915fa","markerVerified":true},"G3":{"sha256":"b562d739deb768e58bfd21d79cf30c7898a0c9a3d944d8fabebd218b4c4c305e","markerVerified":true},"G4":{"sha256":"12fce07f6458aff5db210b0ba50104fa9b2dd52c85b5e9071b48c2899451c631","markerVerified":true},"G6":{"sha256":"84a6159b384b8118f0beaa1089c417cab6d1116cd77d3882a607715ef7679ea8","markerVerified":true},"G7-gnn":{"sha256":"12ca47650a812c66fb5efbbc3b6cdf527ca74ee787f27c9556514492de9d07cd","markerVerified":true},"G7-rvf":{"sha256":"12ca47650a812c66fb5efbbc3b6cdf527ca74ee787f27c9556514492de9d07cd","markerVerified":true},"G7-mut":{"sha256":"12ca47650a812c66fb5efbbc3b6cdf527ca74ee787f27c9556514492de9d07cd","markerVerified":true},"G7-att":{"sha256":"12ca47650a812c66fb5efbbc3b6cdf527ca74ee787f27c9556514492de9d07cd","markerVerified":true},"G7-gvb":{"sha256":"12ca47650a812c66fb5efbbc3b6cdf527ca74ee787f27c9556514492de9d07cd","markerVerified":true},"G2":{"sha256":"881dad4fa9dc19a539c1a46dfe27c77984596cdd05759937909aacf028378acc","markerVerified":true},"CAP-MCP-agent-tools":{"sha256":"fc907ef704fdb0ab2df56019a8956c230cf270c2b8ef00038914d87b9abf4936","markerVerified":true},"CAP-MCP-agentdb-tools":{"sha256":"6ca2c3b6d17e39378a6d95b9ef104a4c7e01c321687a4e21fc5ddc599589f91f","markerVerified":true},"CAP-MCP-analyze-tools":{"sha256":"34c78f417c395ca9df13e53c35c4d47153818f9d10a019e3e299da150c7329c4","markerVerified":true},"CAP-MCP-autopilot-tools":{"sha256":"927df07df0cbe27e8ce0a77ec99529beb62e222649854ef2d1e6d21ad2f446c9","markerVerified":true},"CAP-MCP-browser-tools":{"sha256":"2c075877030bba617709030487675296a9bfddcfc15ea4c30beedbd7d83cf94a","markerVerified":true},"CAP-MCP-claims-tools":{"sha256":"2a00b654e87dd75b9cbb36a0d32e41443c275f5bdf939136c6a397c355f83aa7","markerVerified":true},"CAP-MCP-config-tools":{"sha256":"811ac1297fea330f0e497523a234eb97339a4e1c009b2c33be14915b662b7dec","markerVerified":true},"CAP-MCP-coordination-tools":{"sha256":"5d9b47750015c4626b044453494ef9905ccda9cbb35a06f56215783b6251cef0","markerVerified":true},"CAP-MCP-daa-tools":{"sha256":"90828f0744e1769212a079ef01c13c4a7d2f0d77d6036978a18b94134beef14a","markerVerified":true},"CAP-MCP-embeddings-tools":{"sha256":"6f0f172840b7db1a491356bed5f7b6b6f6e8760633cd38e1bc968f4aa22bc946","markerVerified":true},"CAP-MCP-github-tools":{"sha256":"5987990581843350f1e01490648dd7b85d8e02bbbce8d9551438219e23bef5ec","markerVerified":true},"CAP-MCP-guidance-tools":{"sha256":"c6e4b76e3ea97b9689a8ab7c72f286e653c46e95b59f1f49fe3615f960c1214e","markerVerified":true},"CAP-MCP-hive-mind-tools":{"sha256":"6987df2e11f6c5fe7cb2a4f5b2ba8c883a6705b447b3c0d0f237a2187e5e28a4","markerVerified":true},"CAP-MCP-hooks-tools":{"sha256":"4c255b1d1ac66655551d6c199395f3174cde09f3012e5283f26eb402e7961cac","markerVerified":true},"CAP-MCP-memory-tools":{"sha256":"f1478020eb35302b12e44e97cd99b7b357f84ccbcfd5a1dd5f1d58ad66e52743","markerVerified":true},"CAP-MCP-neural-tools":{"sha256":"7e08b72ac68774af172107f93aba27c5e7254bdb52ba6a8a686da7917fe81e9b","markerVerified":true},"CAP-MCP-performance-tools":{"sha256":"d612f3c006c7c1bf3283c0c257bc24557feff65f8b1f3dbb32c4b9a33478767c","markerVerified":true},"CAP-MCP-progress-tools":{"sha256":"6b9c5c1b27687cfaa1f6b47b245a8b25d98d16418221b0a462f1a11b5b090710","markerVerified":true},"CAP-MCP-ruvllm-tools":{"sha256":"31eb7e4ee42c506685a85008740e83aee2b1d12df6189d4f9bf3f450e0223b37","markerVerified":true},"CAP-MCP-security-tools":{"sha256":"991a2de4462b8a7b29ae26006977fd7b1942bc56fa0e891422d0f28a7e9fff06","markerVerified":true},"CAP-MCP-session-tools":{"sha256":"f623493c80bd305bbf9bf426563db5a9ad745817972bc5690c84a1d1b33e92b9","markerVerified":true},"CAP-MCP-swarm-tools":{"sha256":"fc88476d365dff10b99a1feca048df5aa411b1cc908bd6032dd64a02f7b70a16","markerVerified":true},"CAP-MCP-system-tools":{"sha256":"f4fb8a3a53cb57b71853652a2877c1d337d29306d557cb6fdb993d4e7c2d0c62","markerVerified":true},"CAP-MCP-task-tools":{"sha256":"da3443945cfe91c4f253ead1b26c7c7995c1e89c0a6de3afa063b282de4416c8","markerVerified":true},"CAP-MCP-terminal-tools":{"sha256":"ee54c3dc39f88da154722e1955ed88814e54e653f3b30848e4217eedf2352183","markerVerified":true},"CAP-MCP-transfer-tools":{"sha256":"a58b95f7e702f72d1f142511bdf530116586138b90aca0e2833b8817799ed27f","markerVerified":true},"CAP-MCP-wasm-agent-tools":{"sha256":"114a996d08963a3524447d80eb4c693a1d235eccd877d8b7163caa8f86bcaafa","markerVerified":true},"CAP-MCP-workflow-tools":{"sha256":"b562d739deb768e58bfd21d79cf30c7898a0c9a3d944d8fabebd218b4c4c305e","markerVerified":true},"#1795":{"sha256":"9c9233e068f02511a4c8c310640fc0d3285b449435df5819afa9cc8ac211ff42","markerVerified":true},"#1780":{"sha256":"1d54f3c7589b4e54df60846e29fbe64867f48df5467fc5f44b8bb2fb4b437ad7","markerVerified":true},"#1791.6":{"sha256":"303808b8731937090f104d076495fbe1be43f7cc09d732c4c11f7073e5068653","markerVerified":true},"#1791.7":{"sha256":"bc9739574092e4fad1c5d402720a0d7f50a23b02e78679eec82d8c883dd80703","markerVerified":true},"#1791.2":{"sha256":"381b884d3902a998be261637c13ac4c890e07b165b16437b4eb064c2daaa0381","markerVerified":true},"#1791.5":{"sha256":"bc9739574092e4fad1c5d402720a0d7f50a23b02e78679eec82d8c883dd80703","markerVerified":true},"#1791.4":{"sha256":"ed6a9e9af820c26e8e40905797617628df8ea396493870779a0bc934abcfa10c","markerVerified":true},"#1791.1":{"sha256":"1d54f3c7589b4e54df60846e29fbe64867f48df5467fc5f44b8bb2fb4b437ad7","markerVerified":true},"#1791.8":{"sha256":"f1478020eb35302b12e44e97cd99b7b357f84ccbcfd5a1dd5f1d58ad66e52743","markerVerified":true},"#1799":{"sha256":"fc88476d365dff10b99a1feca048df5aa411b1cc908bd6032dd64a02f7b70a16","markerVerified":true},"#1798":{"sha256":"bc9739574092e4fad1c5d402720a0d7f50a23b02e78679eec82d8c883dd80703","markerVerified":true},"#1810":{"sha256":"12fce07f6458aff5db210b0ba50104fa9b2dd52c85b5e9071b48c2899451c631","markerVerified":true},"#1807":{"sha256":"991a2de4462b8a7b29ae26006977fd7b1942bc56fa0e891422d0f28a7e9fff06","markerVerified":true},"#1686":{"sha256":"91a793c34e0c9bac00923fefde2ec458ef5fc8d0ff73cb2ebd35d55e9e938f3f","markerVerified":true},"#1670":{"sha256":"bba78d719e47c4cd3d56bb08112fde37624432711c02baf9b356bfd480bd837e","markerVerified":true},"#1622":{"sha256":"7f04b21f168c7e00b13bdb7e0811fa83140db66ea2c3b0cf396abba6af3941f5","markerVerified":true},"#1574":{"sha256":"b03341fd433d1523e74b4f407337fefc4b319186bff02620cff89b0193d5b286","markerVerified":true},"#1608":{"sha256":"96b46dd1849fcae990c955dc81703aca8269b2a5d2c69f18003ba9b15bc3f1cf","markerVerified":true},"#1609":{"sha256":"0a9d315b4c1c74b2f86befd070c73a5651d9d1fcdd0b81c38aa2663976952483","markerVerified":true},"#1779":{"sha256":"0c90b9b2bc582e8c872a016de085ca6faa8d837ea43f7bb15ada01d6b67a33d4","markerVerified":true},"#1463":{"sha256":"2e1ec6702dc5dd64c563292414c93c49257ccd26ad1f74589bb3ddb4c1c0938f","markerVerified":true},"#1825":{"sha256":"b6836a525ba4914a9e9a42116bbdbb56449c3505a203611891e21888cc84ac4b","markerVerified":true},"#1834":{"sha256":"ba278b1f9ccf8e170e4cef3748a6bcb4efc0850b7ec66d34690fec328fdabeb1","markerVerified":true},"#1867":{"sha256":"95b39424f3d27658d5f39ac8142c40fad7d10aeb0c439bc924d44ae95e8e74b3","markerVerified":true},"#1859":{"sha256":"91a793c34e0c9bac00923fefde2ec458ef5fc8d0ff73cb2ebd35d55e9e938f3f","markerVerified":true},"#1862":{"sha256":"09c10c262c0bb36301e713e8173090adcdfe345443bff9c4c4aa17fb1e900033","markerVerified":true}}}
diff --git a/verification.md.json b/verification.md.json
index 70b42958da..51be2036a5 100644
--- a/verification.md.json
+++ b/verification.md.json
@@ -1,8 +1,8 @@
{
"manifest": {
"schema": "ruflo-witness/v1",
- "issuedAt": "2026-05-09T00:52:57.167Z",
- "gitCommit": "d4795b75383d5a743de49fc1eb518f887eee606f",
+ "issuedAt": "2026-05-09T01:00:47.879Z",
+ "gitCommit": "54c706f561389888941f5b107bb7e2deea3b076d",
"branch": "main",
"releases": {
"ruflo": "3.7.0-alpha.18",
@@ -668,10 +668,10 @@
},
"integrity": {
"manifestHashAlgo": "sha256",
- "manifestHash": "97b0a18427bea61b81bba3bfcb1dfb386af4d7432b84c91b8c003945db9c7e0c",
+ "manifestHash": "0fb659a57aa21426ab98e8e70fd0ce46bf082afb9b4f5bb710a81d7a19997c24",
"signatureAlgo": "ed25519",
- "publicKey": "c89e93db40e811846867fbc2b845c3cd61c7abd81faf32e0164abeab19db86d9",
- "signature": "8ebf17a36f56d8bb203fa327533c7bd2d5633d6066fef5d5c75f85d6c4aed6e838c80a7ccc3adb3d70a914b7029bb649a1729695c35a563d5b7e2066f68ee906",
+ "publicKey": "0f38b06748adaca43f7a6c4e29ed98aec0c1dca1e537fd86d6e0307519dc85ef",
+ "signature": "df039e63e0426e0e46ad1a822065120606e7b9d4063268053e5ab529e2f84ecc90561c677f98bf391271abc98e45cc7adeae96f97978f88f119f0ad2aea65d09",
"seedDerivation": "sha256(gitCommit + ':ruflo-witness/v1')"
}
}
\ No newline at end of file
diff --git a/witness-fixes.json b/witness-fixes.json
new file mode 100644
index 0000000000..3a4535651f
--- /dev/null
+++ b/witness-fixes.json
@@ -0,0 +1,23 @@
+{
+ "_comment": "Project-specific NEW_FIXES registered on each witness regen. Append { id, desc, file, marker } per shipped fix. Never edit verification.md.json directly β€” re-run scripts/regen-witness.mjs after editing this file.",
+ "fixes": [
+ {
+ "id": "#1867",
+ "desc": "Node 26 install: better-sqlite3 dynamic import + optionalDependencies",
+ "file": "v3/@claude-flow/memory/dist/sqlite-backend.js",
+ "marker": "(await import('better-sqlite3')).default"
+ },
+ {
+ "id": "#1859",
+ "desc": "CLI flag/positional priority swap β€” named flags win over stray positionals (14 sites in hooks.ts)",
+ "file": "v3/@claude-flow/cli/dist/src/commands/hooks.js",
+ "marker": "ctx.flags.file || ctx.args[0]"
+ },
+ {
+ "id": "#1862",
+ "desc": "ruflo-core PostToolUse hooks call documented CLI flags (-c/-s/-e, -f/-s) instead of bogus --format true",
+ "file": "plugins/ruflo-core/hooks/hooks.json",
+ "marker": "hooks post-edit -f \\\"$FILE\\\" -s true"
+ }
+ ]
+}