🌊 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
test(mods): verify configured native guidance and provenance recovery
rUv916199461343
diff --git a/plugins/ruflo-mods/README.md b/plugins/ruflo-mods/README.mdindex 65c3e233b9..634a3a9dfe 100644--- a/plugins/ruflo-mods/README.md+++ b/plugins/ruflo-mods/README.md@@ -149,6 +149,13 @@ pending and dropped observations. These counts are activity, not correctness.CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude plugin test plugins/ruflo-mods # real engine; needs the rollout switch oncd v3/@claude-flow/cli && npx vitest run __tests__/mods/ # declaration-faithful harness, parity testsbash plugins/ruflo-mods/scripts/smoke.sh # static security contract+bash plugins/ruflo-mods/scripts/native-guidance-smoke.sh # three configured native guidance contracts```To typecheck, load the plugin once (Claude Code >= 2.1.287 writes its declarations into `.claude-plugin/types/`), then run `npx tsc -p plugins/ruflo-mods`.++The focused native guidance smoke uses a disposable plugin copy with explicit+feature options because the 2.1.283 test kit ignores per-test option overrides.+It runs the three feature contracts against unchanged production hooks. The+default settings contract belongs to the standard suite. A rollout gate still+applies, and the focused result must not be reported as the complete native suite.diff --git a/plugins/ruflo-mods/scripts/native-guidance-smoke.sh b/plugins/ruflo-mods/scripts/native-guidance-smoke.shnew file mode 100644index 0000000000..261741e686--- /dev/null+++ b/plugins/ruflo-mods/scripts/native-guidance-smoke.sh@@ -0,0 +1,34 @@+#!/usr/bin/env bash+# Focused real engine contracts with explicit feature configuration.+# 2.1.283 ignores the newer testing kit's per-test options. A disposable copy+# enables the feature at registration; every hook implementation stays intact.+# This proves configured native contracts, not the complete native suite.+set -euo pipefail+plugin_root="$(cd "$(dirname "$0")/.." && pwd)"+fixture_root="$(mktemp -d "${TMPDIR:-/tmp}/ruflo-guidance-native.XXXXXX")"+trap 'rm -rf "$fixture_root"' EXIT+python3 - "$plugin_root" "$fixture_root/plugin" <<'PY'+from pathlib import Path+import shutil+import sys++source, fixture = map(Path, sys.argv[1:])+shutil.copytree(source, fixture)+for test in (fixture / 'tests').glob('*.test.ts'):+ if test.name != 'guidance.test.ts':+ test.unlink()++test = fixture / 'tests/guidance.test.ts'+text = test.read_text()+marker = " test('default settings"+assert text.count(marker) == 1, 'Expected the separate default settings contract'+test.write_text(text[:text.index(marker)] + '})\n')++register = fixture / 'hooks/register.ts'+text = register.read_text()+marker = 'readOptions(options)'+assert text.count(marker) == 1, 'Expected the production options injection point'+register.write_text(text.replace(marker, 'readOptions({ ...options, guidanceContext: true, guidanceLearning: true, routeContext: false })'))+print('Configured native guidance fixture: three feature contracts; no hook implementation changed.')+PY+CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 "${RUFLO_NATIVE_TEST_CLAUDE:-claude}" plugin test "$fixture_root/plugin"diff --git a/plugins/ruflo-mods/tests/guidance.test.ts b/plugins/ruflo-mods/tests/guidance.test.tsindex c211d335aa..4c1836503b 100644--- a/plugins/ruflo-mods/tests/guidance.test.ts+++ b/plugins/ruflo-mods/tests/guidance.test.ts@@ -1,8 +1,4 @@import { describe, expect, test, tier } from 'claude-code/testing'-import type { Plugin } from 'claude-code/testing'--import { register } from '../hooks/register'-import { prompt, ROOT, START, world } from './fixtures/world'tier('user')@@ -18,16 +14,11 @@ const projection = () => JSON.stringify({],})const options = { guidanceContext: true, guidanceLearning: true, routeContext: false }-// Exercise production registration directly: the 2.1.283 kit does not apply-// per-test option overrides. Current kits may also run these same contracts.-const enabledGuidance: Plugin = {- name: 'guidance-contract', tier: 'user', register: on => { register(on, options) },-}const complete = (turnId: string, isAborted = false) => ({ answer: 'EXAMPLE_ANSWER_SENTINEL', durationMs: 1, isAborted, turnId, reason: 'answer' }) as constconst queued = (files: Map<string, string>) => [...files].filter(([path]) => path.includes('/guidance/observations/'))describe('guidance (ADR-447)', () => {- test('native prompt context is versioned, screened, bounded and preserves existing content', { plugins: [enabledGuidance] }, async ($, on) => {+ test('native prompt context is versioned, screened, bounded and preserves existing content', { options }, async ($, on) => {world(on, {}, { [PATH]: projection() })let seen: readonly string[] | undefinedon('prompt.submit', ($, e) => { seen = e.context; return { text: e.text } })@@ -42,7 +33,7 @@ describe('guidance (ADR-447)', () => {expect(context.length).toBeLessThan(5000)})- test('native lifecycle stores only unverified metadata once, with failures and final denies', { plugins: [enabledGuidance] }, async ($, on) => {+ test('native lifecycle stores only unverified metadata once, with failures and final denies', { options }, async ($, on) => {const w = world(on, {}, { [PATH]: projection() })on('prompt.submit', ($, e) => ({ text: e.text }))on('tool.check', () => ({ decision: 'deny', reason: 'host rule', rule: 'Read(secret)' }))@@ -62,7 +53,7 @@ describe('guidance (ADR-447)', () => {expect(text).not.toMatch(/SENTINEL|host rule|Read\(secret\)/)})- test('unreadable advisory data leaves prompts flowing and cannot loosen enforcement', { plugins: [enabledGuidance] }, async ($, on) => {+ test('unreadable advisory data leaves prompts flowing and cannot loosen enforcement', { options }, async ($, on) => {const w = world(on, {}, { [PATH]: '{torn', [`${ROOT}/.claude-flow/policy/claude-code.json`]: '{torn' })on('prompt.submit', ($, e) => ({ text: e.text }))on('tool.check', () => ({ decision: 'allow' }))diff --git a/v3/@claude-flow/cli/__tests__/mods/mods-guidance-e2e.test.ts b/v3/@claude-flow/cli/__tests__/mods/mods-guidance-e2e.test.tsindex 83ee8cc760..e6891455d3 100644--- a/v3/@claude-flow/cli/__tests__/mods/mods-guidance-e2e.test.ts+++ b/v3/@claude-flow/cli/__tests__/mods/mods-guidance-e2e.test.ts@@ -7,8 +7,8 @@ import { tmpdir } from 'node:os';import { GuidanceCompiler } from '../../../guidance/src/compiler';import { register } from '../../../../../plugins/ruflo-mods/hooks/register';import { parseProjection, PROJECTION_PATH, MAX_CONTEXT_CHARS, safeText, selectGuidance } from '../../../../../plugins/ruflo-mods/hooks/guidance/projection';-import { finishTask, flushObservations, guidanceState, validObservation, MAX_OBSERVATIONS } from '../../../../../plugins/ruflo-mods/hooks/guidance/observations';-import { buildModProjection, collectModCandidates, MOD_GUIDANCE_DIR, parseModObservations, writeModProjection } from '../../src/guidance/mod-projection';+import { validObservation, MAX_OBSERVATIONS } from '../../../../../plugins/ruflo-mods/hooks/guidance/observations';+import { buildModProjection, collectModCandidates, MOD_GUIDANCE_DIR, parseModObservations } from '../../src/guidance/mod-projection';import { guidanceCommand } from '../../src/commands/guidance';import { output } from '../../src/output';import { loadMod, memoryWorld, realWorld, type World } from './harness';@@ -152,6 +152,30 @@ describe('guidance lifecycle', () => {expect(calls).toBe(1);});+ it('preserves corrupt queue bytes until they are repaired, then flushes pending once', async () => {+ const w = memoryWorld(); seed(w); const mod = await start(w); await prompt(mod); await complete(mod);+ const path = queues(w)[0][0]; const original = files(w).get(path)!.text;+ files(w).set(path, { text: '{corrupt', mtimeMs: 2 });+ await prompt(mod); await complete(mod, 't2');+ expect(files(w).get(path)!.text).toBe('{corrupt');+ files(w).set(path, { text: original, mtimeMs: 3 });+ await end(mod); await end(mod);+ expect(records(w)).toHaveLength(2);+ });++ it('binds each turn to its displayed version and does not attribute undisplayed guidance', async () => {+ const w = memoryWorld(); const first = projection(); seed(w, first); const mod = await start(w);+ await prompt(mod); await complete(mod, 't1');+ const second = buildModProjection(new GuidanceCompiler().compile(SOURCE + '\n- TEST-002: Always test invalid parser inputs.\n'), 'd'.repeat(40));+ files(w).set(`${w.root}/${PROJECTION_PATH}`, { text: JSON.stringify(second), mtimeMs: 2 });+ await prompt(mod); await complete(mod, 't2');+ expect(records(w).map(r => r.bundleId)).toEqual([first.bundleId, second.bundleId]);+ const invisible = memoryWorld(); seed(invisible);+ const observe = await start(invisible, { guidanceContext: false, guidanceLearning: true });+ await prompt(observe); await complete(observe);+ expect(records(invisible)[0].ruleIds).toEqual([]);+ });+it('uses a distinct queue on reload and leaves classic hook ownership intact', async () => {const w = memoryWorld('/work', { hooks: { UserPromptSubmit: [{ hooks: [{ command: 'node .claude/helpers/hook-handler.cjs route' }] }] } });seed(w); files(w).set('/work/.claude/helpers/hook-handler.cjs', { text: '// older helper', mtimeMs: 1 });diff --git a/v3/@claude-flow/cli/src/guidance/mod-projection.ts b/v3/@claude-flow/cli/src/guidance/mod-projection.tsindex 436c2f1848..c2ec780cb8 100644--- a/v3/@claude-flow/cli/src/guidance/mod-projection.ts+++ b/v3/@claude-flow/cli/src/guidance/mod-projection.ts@@ -23,6 +23,22 @@ const HEX = /^[a-f0-9]{64}$/;const RUN = /^mod-[a-z0-9]+-[a-z0-9]{1,12}-[a-z0-9]{1,12}$/;const ID = /^[A-Za-z0-9_-]{1,64}$/;+export interface ModObservation {+ version: 1;+ kind: 'guidance-observation';+ id: string;+ runId: string;+ taskId: number;+ bundleId: string;+ sourceRevision: string;+ ruleIds: string[];+ checks: { allow: number; ask: number; deny: number };+ tools: { ok: number; error: number; denied: number };+ completion: 'completed' | 'aborted' | 'interrupted';+ verified: false;+ learningEligible: false;+}+/** Stable digest of the exported rules; a provenance identifier, not a signature. */export function buildModProjection(bundle: Bundle, sourceRevision: string) {if (!/^[a-f0-9]{40,64}$/.test(sourceRevision)) throw new Error('--revision must be an immutable source commit SHA');@@ -60,7 +76,7 @@ const keys = ['version', 'kind', 'id', 'runId', 'taskId', 'bundleId', 'sourceRevconst counters = (value: any, names: string[]) => value && !Array.isArray(value) && Object.keys(value).length === names.length && names.every(k => Number.isSafeInteger(value[k]) && value[k] >= 0 && value[k] <= 100000);/** Strict allowlist: a writable `verified: true` or receipt cannot become evidence. */-export function parseModObservations(text: string): any[] {+export function parseModObservations(text: string): ModObservation[] {if (Buffer.byteLength(text) > MAX_BYTES) throw new Error('Observation file exceeds 256 KiB');const records = JSON.parse(text);if (!Array.isArray(records) || records.length > 128) throw new Error('Invalid observation queue');