@claude-flow/cli 3.38.23 → 3.39.0

package/.claude/helpers/helpers.manifest.json

@@ -1,6 +1,6 @@
 {
   "manifest": {
-    "version": "3.38.23",
+    "version": "3.39.0",
     "files": {
       "auto-memory-hook.mjs": "85fe05c757421c52137c0bc8545a0896bab6b4714538c2a11d1d0835bfcc8c1c",
       "hook-handler.cjs": "209d9fafe10e17d1be0866727f6f9cf9ac66f9a0793f1c793a4f58319e8e4583",
@@ -8,6 +8,6 @@
       "statusline.cjs": "4a48353b4f1566fa4379b00fd0321b6676a22b6cc91fbbd8380ac5183d619468"
     }
   },
-  "signature": "TJPmjOW/sxuw75iuKo1IeJNrgRT42msZz/euuryYE/SLd5XPUmROZLfMgzl0yvDyvHeOYZ3j+P3VI62fCFZ1DQ==",
+  "signature": "ezHXe7aYuhhtcjCgjytboA5ImEY+bpGDC7eJXkqXPmlVHtNyG6I0DPoBUV2SPSeyf4VRRjME3gdANH35XSMmDg==",
   "algorithm": "ed25519"
 }

package/README.md

@@ -21,6 +21,11 @@
 
 **An agent meta-harness for Claude Code and Codex.**
 
+[![RuFlo Explained — build an AI team that plans, remembers, tests, and improves](docs/assets/ruflo-explained/ch14.jpg)](docs/ruflo-explained.md)
+
+**[📖 RuFlo Explained — Build an AI Team That Plans, Remembers, Tests, and Improves](docs/ruflo-explained.md)**
+A 14-chapter guide: from the basic idea to a first useful task, then memory, agent teams, plugins, cost and verification.
+
 </div>
 
 > **Agent = Model + Harness.** The model writes; the harness gives it tools, memory, loops, sandboxes, and controls so it can actually work. **Ruflo is the harness** — the execution layer around Claude Code and Codex that adds 100+ specialized agents, coordinated swarms, self-learning memory, federated comms across machines, and enterprise security guardrails. So agents don't just run, they collaborate.

package/catalog-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "generation": 6,
-  "generatedAt": "2026-09-07T17:34:20.768Z",
-  "gitSha": "6acc6891",
+  "generatedAt": "2026-09-08T16:51:58.984Z",
+  "gitSha": "e341ec8c",
   "catalog": {
     "agents": 167,
     "tools": 397,

package/dist/src/services/flywheel-receipt.d.ts

@@ -139,9 +139,44 @@ export declare function collectUnknownReceiptFields(receipt: FlywheelEvaluationR
  */
 export declare function canonicalizeJcs(value: unknown): string;
 export declare function sha256Ref(value: string | Buffer): string;
+/**
+ * Enforce ADR-322C rule 2 / conformance-checklist A3 over a receipt payload:
+ * "Every fractional value is a canonical decimal string, not a binary float."
+ *
+ * This lives at the RECEIPT boundary rather than inside `canonicalizeJcs`,
+ * which is shared with the proposer envelope (`flywheel-proposer.ts`) and the
+ * promotion ledger (`flywheel-transaction.ts`) — structures the contract does
+ * not govern. A first attempt put the check in the canonicalizer and broke
+ * those callers, which is the reason the scope is spelled out here.
+ *
+ * Integers and scaled integers stay JSON numbers (currency micros, durations,
+ * iteration counts). A fractional JSON number anywhere in the payload is a
+ * contract violation, and the error names the path — the original bug
+ * (ruvnet/ruflo#3229) needed a live fixture to find precisely because neither
+ * verifier said which field was wrong.
+ */
+export declare function assertReceiptNumberDomain(value: unknown, path?: string): void;
 export declare function policyCandidateId(policy: Record<string, unknown>): string;
 /** UUIDv7 with a 48-bit millisecond timestamp and RFC-4122 variant bits. */
 export declare function uuidV7(now?: number): string;
+/**
+ * Encode an opaque policy object so every fractional value is a scale-12
+ * decimal string, per ADR-322C rule 2 and conformance-checklist A3.
+ *
+ * `candidatePolicy` is declared "Opaque to this contract; its shape is owned by
+ * policySchemaVersion. Must still satisfy the ADR-322C number rules" — a rule
+ * the JSON Schema cannot express for an opaque object, so nothing enforced it
+ * and the producer wrote binary floats (`{"alpha": 0.3, "mmrLambda": 0.5}`).
+ * Ruflo's own verifier accepted them because `assertJsonValue` only checked
+ * finite-and-not-negative-zero; autogenous's stricter verifier correctly
+ * rejected the receipt (ruvnet/ruflo#3229, ruvnet/autogenous#15).
+ *
+ * Integers stay JSON numbers and only non-integers are encoded, which is what
+ * the contract's own example shows: `{"hnswEf": 128, "hybridWeight": "0.65"}`.
+ * Recurses through nested objects and arrays, because "every fractional value"
+ * is not limited to the top level.
+ */
+export declare function encodePolicyFractions(value: unknown): unknown;
 export declare function computePromotionStatistics(input: {
     baselineScore: number;
     candidateScore: number;

package/dist/src/services/flywheel-receipt.js

@@ -123,8 +123,47 @@ export function canonicalizeJcs(value) {
 export function sha256Ref(value) {
     return `sha256:${createHash('sha256').update(value).digest('hex')}`;
 }
+/**
+ * Enforce ADR-322C rule 2 / conformance-checklist A3 over a receipt payload:
+ * "Every fractional value is a canonical decimal string, not a binary float."
+ *
+ * This lives at the RECEIPT boundary rather than inside `canonicalizeJcs`,
+ * which is shared with the proposer envelope (`flywheel-proposer.ts`) and the
+ * promotion ledger (`flywheel-transaction.ts`) — structures the contract does
+ * not govern. A first attempt put the check in the canonicalizer and broke
+ * those callers, which is the reason the scope is spelled out here.
+ *
+ * Integers and scaled integers stay JSON numbers (currency micros, durations,
+ * iteration counts). A fractional JSON number anywhere in the payload is a
+ * contract violation, and the error names the path — the original bug
+ * (ruvnet/ruflo#3229) needed a live fixture to find precisely because neither
+ * verifier said which field was wrong.
+ */
+export function assertReceiptNumberDomain(value, path = '$') {
+    if (typeof value === 'number') {
+        if (!Number.isInteger(value)) {
+            throw new Error(`fractional number at ${path} must be a scale-12 decimal string (ADR-322C rule 2)`);
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((v, i) => assertReceiptNumberDomain(v, `${path}[${i}]`));
+        return;
+    }
+    if (value && typeof value === 'object') {
+        for (const [k, v] of Object.entries(value)) {
+            assertReceiptNumberDomain(v, `${path}.${k}`);
+        }
+    }
+}
 export function policyCandidateId(policy) {
-    return sha256Ref(canonicalizeJcs(policy));
+    // Encode at the hashing boundary so the content ID is always over the
+    // CANONICAL form, whether the caller passed a raw config or an
+    // already-encoded policy. `encodePolicyFractions` is idempotent — an
+    // encoded value is a string and passes through untouched — so
+    // policyCandidateId(raw) === policyCandidateId(encoded), which is what lets
+    // `verify` recompute the ID from the payload and still match.
+    return sha256Ref(canonicalizeJcs(encodePolicyFractions(policy)));
 }
 /** UUIDv7 with a 48-bit millisecond timestamp and RFC-4122 variant bits. */
 export function uuidV7(now = Date.now()) {
@@ -143,6 +182,38 @@ const decimal = (value, scale = 12) => {
     const normalized = value.toFixed(scale).replace(/\.?0+$/, '');
     return normalized === '-0' || normalized === '' ? '0' : normalized;
 };
+/**
+ * Encode an opaque policy object so every fractional value is a scale-12
+ * decimal string, per ADR-322C rule 2 and conformance-checklist A3.
+ *
+ * `candidatePolicy` is declared "Opaque to this contract; its shape is owned by
+ * policySchemaVersion. Must still satisfy the ADR-322C number rules" — a rule
+ * the JSON Schema cannot express for an opaque object, so nothing enforced it
+ * and the producer wrote binary floats (`{"alpha": 0.3, "mmrLambda": 0.5}`).
+ * Ruflo's own verifier accepted them because `assertJsonValue` only checked
+ * finite-and-not-negative-zero; autogenous's stricter verifier correctly
+ * rejected the receipt (ruvnet/ruflo#3229, ruvnet/autogenous#15).
+ *
+ * Integers stay JSON numbers and only non-integers are encoded, which is what
+ * the contract's own example shows: `{"hnswEf": 128, "hybridWeight": "0.65"}`.
+ * Recurses through nested objects and arrays, because "every fractional value"
+ * is not limited to the top level.
+ */
+export function encodePolicyFractions(value) {
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new Error('policy value must be finite');
+        // Integers are exact in JSON and the contract permits scaled integers, so
+        // they are left alone; -0 is normalized away by `decimal`.
+        return Number.isInteger(value) && !Object.is(value, -0) ? value : decimal(value);
+    }
+    if (Array.isArray(value))
+        return value.map(encodePolicyFractions);
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, encodePolicyFractions(v)]));
+    }
+    return value;
+}
 function seedFrom(parts) {
     const digest = createHash('sha256').update(parts.join('')).digest();
     return { seed: digest.readUInt32BE(0), hex: digest.toString('hex') };
@@ -239,6 +310,10 @@ function receiptIdentityPayload(payload) {
     return payload;
 }
 function signedBytes(payload) {
+    // Assert at the signing boundary: a receipt must never be SIGNED unless it
+    // satisfies the number domain it claims. Covers both produce and verify,
+    // since both paths sign or re-derive these bytes.
+    assertReceiptNumberDomain(payload);
     return Buffer.concat([
         Buffer.from(RECEIPT_DOMAIN, 'utf8'),
         Buffer.from([0]),
@@ -249,7 +324,12 @@ export function createFlywheelReceipt(input) {
     const now = input.now ?? Date.now();
     const evaluationRunId = input.evaluationRunId ?? uuidV7(now);
     const lineageId = input.lineageId ?? uuidV7(now);
-    const candidateId = policyCandidateId(input.candidatePolicy);
+    // Encode ONCE and use the encoded object for both the candidate content ID
+    // and the payload, so `verify`'s recomputation of policyCandidateId still
+    // matches. Encoding after the ID were computed would make every receipt fail
+    // its own 'candidate content ID mismatch' check.
+    const candidatePolicy = encodePolicyFractions(input.candidatePolicy);
+    const candidateId = policyCandidateId(candidatePolicy);
     // Verifiers recompute the statistics from the payload's scale-12 decimal
     // strings — the only values they ever have. The encoded values are therefore
     // the statistical inputs of record: compute the decision from them, not from
@@ -277,9 +357,23 @@ export function createFlywheelReceipt(input) {
         evaluationRunId,
         baselineRef: input.baselineRef,
         expectedLedgerHead: input.expectedLedgerHead ?? GENESIS_LEDGER_HEAD,
-        candidatePolicy: input.candidatePolicy,
+        candidatePolicy,
         gateVersion: input.gateVersion ?? statistics.ruleVersion,
-        policySchemaVersion: input.policySchemaVersion ?? 'ruflo.retrieval-policy/v1',
+        // v1 -> v2: the encoding of `candidatePolicy` changed (#3229). Fixing it
+        // changes the candidate content ID, so a pre-fix receipt can never match a
+        // post-fix champion reference. Bumping the schema version makes the
+        // promotion gate refuse those receipts with an ACCURATE reason —
+        // 'policy schema changed' (flywheel-transaction.ts:468) — instead of a
+        // confusing 'stale baseline' hash mismatch.
+        //
+        // Signed receipts are deliberately NOT migrated: re-encoding changes the
+        // content, which changes the ID, which invalidates the signature. A
+        // migration would mean re-signing, i.e. minting new receipts that claim to
+        // be old ones, which is what the receipt design exists to prevent. Existing
+        // receipts stay valid as history and unpromotable; the champion is
+        // re-established through the explicit reset path, which already requires
+        // confirmation and a recorded reason.
+        policySchemaVersion: input.policySchemaVersion ?? 'ruflo.retrieval-policy/v2',
         safetyEnvelopeRef: input.safetyEnvelopeRef,
         ...(input.anchorRef ? { anchorRef: input.anchorRef } : {}),
         requestedProposer: input.requestedProposer ?? 'local',
@@ -342,6 +436,17 @@ export function createFlywheelReceipt(input) {
     return receipt;
 }
 export function verifyFlywheelReceipt(receipt, trustedPublicKeys) {
+    // The enforcement half of #3229. Before this, ruflo verified its own
+    // non-conforming receipts because the only number rule was
+    // finite-and-not-negative-zero, while autogenous's stricter verifier
+    // correctly rejected them. Reported as an error rather than thrown so the
+    // caller gets it alongside every other finding.
+    try {
+        assertReceiptNumberDomain(receipt.payload);
+    }
+    catch (err) {
+        return { valid: false, signed: !!receipt.signature, errors: [err.message] };
+    }
     const errors = [];
     try {
         if (receipt.payload.schemaVersion !== RECEIPT_SCHEMA)

package/dist/src/services/harness-flywheel.js

@@ -216,7 +216,12 @@ export async function evaluateFlywheelCandidate(projectRoot, deps) {
             evaluationRunId: deps.evaluationRunId,
             baselineRef: refOf(baseline),
             expectedLedgerHead: txState.ledgerHead,
-            candidatePolicy: candidate,
+            // `as unknown as` erased RetrievalConfig's `number` fields and laundered
+            // binary floats into a receipt claiming ADR-322C conformance (#3229).
+            // createFlywheelReceipt now encodes fractional values to scale-12
+            // decimal strings, so a single structural cast is enough and the
+            // type-erasing double cast is gone.
+            candidatePolicy: { ...candidate },
             safetyEnvelopeRef,
             anchorRef: deps.anchorRef,
             requestedProposer: deps.requestedProposer ?? 'local',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.38.23",
+  "version": "3.39.0",
   "type": "module",
   "description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",