π 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
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
feat: ADR-103 witness temporal history + plugin-distributed toolkit (#1868)
Reuven76bd35943a3e
diff --git a/.github/workflows/v3-ci.yml b/.github/workflows/v3-ci.ymlindex 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-latestdiff --git a/plugins/ruflo-core/agents/witness-curator.md b/plugins/ruflo-core/agents/witness-curator.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.mjsnew file mode 100644index 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.mdnew file mode 100644index 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.mjsindex 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.mdnew file mode 100644index 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.jsonlnew file mode 100644index 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.jsonindex 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 filediff --git a/witness-fixes.json b/witness-fixes.jsonnew file mode 100644index 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"+ }+ ]+}