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

test(mods): verify configured native guidance and provenance recovery

rUv916199461343
diff --git a/plugins/ruflo-mods/README.md b/plugins/ruflo-mods/README.md
index 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 on
cd v3/@claude-flow/cli && npx vitest run __tests__/mods/ # declaration-faithful harness, parity tests
bash 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.sh
new file mode 100644
index 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.ts
index 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 const
const 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[] | undefined
on('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.ts
index 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.ts
index 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', 'sourceRev
const 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');