@claude-flow/cli 3.65.0 → 3.66.0

package/dist/src/mcp-tools/http-fetch-pinned.d.ts

@@ -0,0 +1,44 @@
+/**
+ * http_fetch's address checks and connection-pinned transport (ADR-164 §5.1.8).
+ *
+ * Checking the URL's hostname string is not enough: a public-looking name can resolve to
+ * loopback, RFC-1918 or cloud metadata (169.254.169.254), and `fetch()` resolves the name
+ * again on its own, so even a pre-resolution check can be rebound (TTL-0 DNS) between the
+ * check and the connect. Here the socket's DNS lookup *is* the check: `pinnedLookup`
+ * resolves the name, refuses it when any address is private, and hands the socket only the
+ * addresses it checked, so the connection cannot land anywhere else. IP-literal hosts never
+ * reach a lookup; `validateUrl` checks those by text, with the same `isPrivateOrLoopback`.
+ *
+ * @module @claude-flow/cli/mcp-tools/http-fetch-pinned
+ */
+import { type LookupFunction } from 'node:net';
+/** Raised when a hostname resolves to an address the allowlist refuses. */
+export declare class PrivateAddressError extends Error {
+    readonly code = "PRIVATE_ADDRESS";
+    constructor(host: string, address: string);
+}
+export declare const allowPrivateAddresses: () => boolean;
+/**
+ * Whether a host (an IP literal, bracketed or not, or `localhost`) is one http_fetch refuses
+ * by default. A name that is not an IP literal is `false` here: what it resolves to is
+ * checked at connect time by `pinnedLookup`.
+ */
+export declare function isPrivateOrLoopback(host: string): boolean;
+/**
+ * The socket's DNS lookup: resolve every address, refuse the host when any of them is
+ * private (unless opted in), and return only those checked addresses to the socket.
+ */
+export declare const pinnedLookup: LookupFunction;
+export interface PinnedInit {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal: AbortSignal;
+}
+/**
+ * One HTTP(S) request whose connection goes only to an address `pinnedLookup` checked, with
+ * no redirect following and a fresh connection every time (no pooled socket from elsewhere).
+ * Returns a standard `Response` so the caller reads it as it would a `fetch()` result.
+ */
+export declare function pinnedRequest(url: string, init: PinnedInit): Promise<Response>;
+//# sourceMappingURL=http-fetch-pinned.d.ts.map

package/dist/src/mcp-tools/http-fetch-pinned.js

@@ -0,0 +1,148 @@
+/**
+ * http_fetch's address checks and connection-pinned transport (ADR-164 §5.1.8).
+ *
+ * Checking the URL's hostname string is not enough: a public-looking name can resolve to
+ * loopback, RFC-1918 or cloud metadata (169.254.169.254), and `fetch()` resolves the name
+ * again on its own, so even a pre-resolution check can be rebound (TTL-0 DNS) between the
+ * check and the connect. Here the socket's DNS lookup *is* the check: `pinnedLookup`
+ * resolves the name, refuses it when any address is private, and hands the socket only the
+ * addresses it checked, so the connection cannot land anywhere else. IP-literal hosts never
+ * reach a lookup; `validateUrl` checks those by text, with the same `isPrivateOrLoopback`.
+ *
+ * @module @claude-flow/cli/mcp-tools/http-fetch-pinned
+ */
+import { lookup as dnsLookup } from 'node:dns';
+import * as http from 'node:http';
+import * as https from 'node:https';
+import { isIP } from 'node:net';
+import { Readable } from 'node:stream';
+/** Raised when a hostname resolves to an address the allowlist refuses. */
+export class PrivateAddressError extends Error {
+    code = 'PRIVATE_ADDRESS';
+    constructor(host, address) {
+        super(`host ${host} resolves to ${address}, which is loopback/private/link-local; set CLAUDE_FLOW_HTTP_FETCH_ALLOW_PRIVATE=1 to override`);
+        this.name = 'PrivateAddressError';
+    }
+}
+export const allowPrivateAddresses = () => process.env.CLAUDE_FLOW_HTTP_FETCH_ALLOW_PRIVATE === '1';
+/** The 16-bit groups of an IPv6 address (brackets stripped), or null when it is not one. */
+function ipv6Groups(addr) {
+    if (isIP(addr) !== 6)
+        return null;
+    let text = addr.split('%')[0];
+    // A trailing dotted IPv4 (`::ffff:1.2.3.4`) is two groups.
+    const v4 = text.match(/(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (v4) {
+        const [a, b, c, d] = v4.slice(1).map(Number);
+        text = `${text.slice(0, v4.index)}${((a << 8) | b).toString(16)}:${((c << 8) | d).toString(16)}`;
+    }
+    const [head, tail] = text.includes('::') ? text.split('::') : [text, undefined];
+    const parse = (s) => (s ? s.split(':').map((g) => parseInt(g, 16)) : []);
+    const h = parse(head);
+    const t = tail === undefined ? [] : parse(tail);
+    const groups = tail === undefined ? h : [...h, ...new Array(8 - h.length - t.length).fill(0), ...t];
+    return groups.length === 8 && groups.every((g) => Number.isInteger(g) && g >= 0 && g <= 0xffff) ? groups : null;
+}
+function privateIPv4(a, b) {
+    return a === 0 // 0.0.0.0/8 ("this" network)
+        || a === 127 // loopback
+        || a === 10 // RFC 1918
+        || (a === 172 && b >= 16 && b <= 31) // RFC 1918
+        || (a === 192 && b === 168) // RFC 1918
+        || (a === 169 && b === 254) // link-local, cloud metadata
+        || (a === 100 && b >= 64 && b <= 127) // CGNAT
+        || (a === 198 && (b === 18 || b === 19)) // benchmarking
+        || a >= 224; // multicast, reserved, broadcast
+}
+/**
+ * Whether a host (an IP literal, bracketed or not, or `localhost`) is one http_fetch refuses
+ * by default. A name that is not an IP literal is `false` here: what it resolves to is
+ * checked at connect time by `pinnedLookup`.
+ */
+export function isPrivateOrLoopback(host) {
+    const lower = host.toLowerCase();
+    if (lower === 'localhost' || lower === 'localhost.localdomain' || lower.endsWith('.localhost'))
+        return true;
+    const bare = lower.startsWith('[') && lower.endsWith(']') ? lower.slice(1, -1) : lower;
+    const v4 = bare.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (v4)
+        return privateIPv4(Number(v4[1]), Number(v4[2]));
+    const g = ipv6Groups(bare);
+    if (!g)
+        return false;
+    const embedded = (hi) => privateIPv4(hi >> 8, hi & 0xff);
+    if (g.slice(0, 7).every((x) => x === 0) && g[7] <= 1)
+        return true; // :: and ::1
+    if (g.slice(0, 5).every((x) => x === 0) && g[5] === 0xffff)
+        return embedded(g[6]); // ::ffff:a.b.c.d (IPv4-mapped)
+    if (g.slice(0, 6).every((x) => x === 0))
+        return true; // ::a.b.c.d (deprecated IPv4-compatible)
+    if (g[0] === 0x64 && g[1] === 0xff9b)
+        return true; // 64:ff9b::/96 and /48 NAT64: may wrap any IPv4
+    if (g[0] === 0x2002)
+        return embedded(g[1]); // 6to4 carries an IPv4
+    if ((g[0] & 0xfe00) === 0xfc00)
+        return true; // fc00::/7 unique local
+    if ((g[0] & 0xffc0) === 0xfe80 || (g[0] & 0xffc0) === 0xfec0)
+        return true; // fe80::/10 link-local, fec0::/10 site-local
+    if ((g[0] & 0xff00) === 0xff00)
+        return true; // ff00::/8 multicast
+    return false;
+}
+/**
+ * The socket's DNS lookup: resolve every address, refuse the host when any of them is
+ * private (unless opted in), and return only those checked addresses to the socket.
+ */
+export const pinnedLookup = (hostname, options, callback) => {
+    dnsLookup(hostname, { ...options, all: true }, (err, addresses) => {
+        if (err)
+            return callback(err, []);
+        const list = addresses;
+        if (!allowPrivateAddresses()) {
+            const bad = list.find((a) => isPrivateOrLoopback(a.address));
+            if (bad || list.length === 0) {
+                return callback(new PrivateAddressError(hostname, bad?.address ?? 'no address'), []);
+            }
+        }
+        if (options.all)
+            return callback(null, list);
+        callback(null, list[0].address, list[0].family);
+    });
+};
+/** Statuses whose Response must not carry a body. */
+const NULL_BODY = new Set([101, 103, 204, 205, 304]);
+/**
+ * One HTTP(S) request whose connection goes only to an address `pinnedLookup` checked, with
+ * no redirect following and a fresh connection every time (no pooled socket from elsewhere).
+ * Returns a standard `Response` so the caller reads it as it would a `fetch()` result.
+ */
+export function pinnedRequest(url, init) {
+    const target = new URL(url);
+    const client = target.protocol === 'https:' ? https : http;
+    const headers = { accept: '*/*', ...init.headers };
+    if (init.body !== undefined && !Object.keys(headers).some((k) => k.toLowerCase() === 'content-length')) {
+        headers['content-length'] = String(Buffer.byteLength(init.body));
+    }
+    return new Promise((resolve, reject) => {
+        const req = client.request(target, { method: init.method, headers, lookup: pinnedLookup, agent: false, signal: init.signal }, (res) => {
+            const out = new Headers();
+            for (const [key, value] of Object.entries(res.headers)) {
+                for (const v of Array.isArray(value) ? value : value === undefined ? [] : [value])
+                    out.append(key, v);
+            }
+            const status = res.statusCode ?? 0;
+            if (status < 200 || status > 599) {
+                res.destroy();
+                reject(new Error(`unsupported HTTP status ${status}`));
+                return;
+            }
+            const body = NULL_BODY.has(status) || init.method === 'HEAD' ? null : Readable.toWeb(res);
+            if (body === null)
+                res.resume();
+            resolve(new Response(body, { status, statusText: res.statusMessage ?? '', headers: out }));
+        });
+        req.on('error', reject);
+        req.end(init.body);
+    });
+}
+//# sourceMappingURL=http-fetch-pinned.js.map

package/dist/src/mcp-tools/http-fetch-tools.d.ts

@@ -11,7 +11,10 @@
  * AbortController, response truncation, default User-Agent.
  *
  * Architectural constraints (load-bearing):
- *   - DEFAULT-REFUSES private addresses + loopback (CLAUDE_FLOW_HTTP_FETCH_ALLOW_PRIVATE=1 opt-in)
+ *   - DEFAULT-REFUSES private addresses + loopback (CLAUDE_FLOW_HTTP_FETCH_ALLOW_PRIVATE=1 opt-in):
+ *     IP literals by text here, and every resolved address of a hostname at connect time, on the
+ *     connection itself (http-fetch-pinned.ts), so DNS that points at, or rebinds to, a private
+ *     address is refused too
  *   - DEFAULT-REFUSES Authorization / Cookie / X-Auth-* (CLAUDE_FLOW_HTTP_FETCH_ALLOW_AUTH=1 opt-in)
  *   - hard timeout 30s default, 60s ceiling
  *   - response truncated to 256KB default, 1MB ceiling
@@ -20,6 +23,8 @@
  * @module @claude-flow/cli/mcp-tools/http-fetch
  */
 import type { MCPTool } from './types.js';
+import { type PinnedInit } from './http-fetch-pinned.js';
+export { isPrivateOrLoopback } from './http-fetch-pinned.js';
 export declare class HttpFetchValidationError extends Error {
     readonly code: string;
     constructor(message: string, code: string);
@@ -45,11 +50,15 @@ export interface HttpFetchResult {
     error?: string;
     errorCode?: string;
 }
+/** How one request is sent; tests replace it to script responses. The default pins each connection to checked addresses. */
+export type HttpFetchRequest = (url: string, init: PinnedInit) => Promise<Response>;
 /**
  * Pure execution path so tests can call it without going through the MCP
  * dispatcher. Returns a result object (does not throw on validation failure
  * — it returns success: false with an errorCode).
  */
-export declare function httpFetchExecute(input: Record<string, unknown>): Promise<HttpFetchResult>;
+export declare function httpFetchExecute(input: Record<string, unknown>, deps?: {
+    request?: HttpFetchRequest;
+}): Promise<HttpFetchResult>;
 export declare const httpFetchTools: MCPTool[];
 //# sourceMappingURL=http-fetch-tools.d.ts.map

package/dist/src/mcp-tools/http-fetch-tools.js

@@ -11,7 +11,10 @@
  * AbortController, response truncation, default User-Agent.
  *
  * Architectural constraints (load-bearing):
- *   - DEFAULT-REFUSES private addresses + loopback (CLAUDE_FLOW_HTTP_FETCH_ALLOW_PRIVATE=1 opt-in)
+ *   - DEFAULT-REFUSES private addresses + loopback (CLAUDE_FLOW_HTTP_FETCH_ALLOW_PRIVATE=1 opt-in):
+ *     IP literals by text here, and every resolved address of a hostname at connect time, on the
+ *     connection itself (http-fetch-pinned.ts), so DNS that points at, or rebinds to, a private
+ *     address is refused too
  *   - DEFAULT-REFUSES Authorization / Cookie / X-Auth-* (CLAUDE_FLOW_HTTP_FETCH_ALLOW_AUTH=1 opt-in)
  *   - hard timeout 30s default, 60s ceiling
  *   - response truncated to 256KB default, 1MB ceiling
@@ -19,6 +22,8 @@
  *
  * @module @claude-flow/cli/mcp-tools/http-fetch
  */
+import { allowPrivateAddresses, isPrivateOrLoopback, pinnedRequest, PrivateAddressError } from './http-fetch-pinned.js';
+export { isPrivateOrLoopback } from './http-fetch-pinned.js';
 const DEFAULT_TIMEOUT_MS = 30_000;
 const MAX_TIMEOUT_MS = 60_000;
 const DEFAULT_MAX_RESPONSE_BYTES = 256 * 1024; // 256 KB
@@ -54,75 +59,11 @@ export function validateUrl(rawUrl) {
         throw new HttpFetchValidationError(`protocol ${parsed.protocol} not allowed (only http: and https:)`, 'FORBIDDEN_PROTOCOL');
     }
     const host = parsed.hostname.toLowerCase();
-    const allowPrivate = process.env.CLAUDE_FLOW_HTTP_FETCH_ALLOW_PRIVATE === '1';
-    if (!allowPrivate && isPrivateOrLoopback(host)) {
+    if (!allowPrivateAddresses() && isPrivateOrLoopback(host)) {
         throw new HttpFetchValidationError(`host ${host} is loopback/private/link-local; set CLAUDE_FLOW_HTTP_FETCH_ALLOW_PRIVATE=1 to override`, 'PRIVATE_ADDRESS');
     }
     return parsed;
 }
-function isPrivateOrLoopback(host) {
-    if (host === 'localhost' || host === 'localhost.localdomain')
-        return true;
-    // Node's URL parser keeps brackets in `.hostname` for every IPv6 literal
-    // (e.g. "[::1]", "[fc00::1]", "[::ffff:7f00:1]"). Strip them once so every
-    // check below operates on the bare address — without this, the fc00::/7
-    // and fe80::/10 checks further down never match anything (they test
-    // `startsWith('fc'/'fe80:')` against a string starting with "["), and an
-    // IPv4-mapped-IPv6 literal (`::ffff:a.b.c.d`, which Node normalizes to a
-    // canonical `::ffff:xxxx:yyyy` hex form) sails through both the IPv4 and
-    // IPv6 branches untested — a live SSRF bypass (e.g. `::ffff:127.0.0.1` or
-    // `::ffff:169.254.169.254` reaching loopback / cloud-metadata targets).
-    const bare = host.startsWith('[') && host.endsWith(']') ? host.slice(1, -1) : host;
-    if (bare === '::1')
-        return true; // IPv6 loopback
-    // IPv4-mapped IPv6 — decode back to dotted-decimal and recurse into the
-    // IPv4 check below so it inherits every existing private/loopback/
-    // link-local/CGNAT rule instead of needing its own copy.
-    const mappedHex = bare.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
-    if (mappedHex) {
-        const hi = parseInt(mappedHex[1], 16);
-        const lo = parseInt(mappedHex[2], 16);
-        const decoded = `${(hi >> 8) & 0xff}.${hi & 0xff}.${(lo >> 8) & 0xff}.${lo & 0xff}`;
-        return isPrivateOrLoopback(decoded);
-    }
-    const mappedDecimal = bare.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
-    if (mappedDecimal)
-        return isPrivateOrLoopback(mappedDecimal[1]);
-    // IPv4 numeric checks
-    const m = bare.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
-    if (m) {
-        const a = Number(m[1]);
-        const b = Number(m[2]);
-        if (a === 0)
-            return true; // 0.0.0.0/8
-        if (a === 127)
-            return true; // loopback
-        if (a === 10)
-            return true; // RFC1918
-        if (a === 172 && b >= 16 && b <= 31)
-            return true; // RFC1918
-        if (a === 192 && b === 168)
-            return true; // RFC1918
-        if (a === 169 && b === 254)
-            return true; // link-local
-        if (a === 100 && b >= 64 && b <= 127)
-            return true; // CGNAT
-        return false;
-    }
-    // IPv6 special forms — be conservative and accept only public-looking
-    // literals. Reject obvious private/local forms.
-    if (bare.startsWith('fc') || bare.startsWith('fd'))
-        return true; // fc00::/7 ULA
-    if (bare.startsWith('fe80:'))
-        return true; // link-local
-    // KNOWN LIMITATION (pre-existing, not introduced by the bracket-stripping /
-    // IPv4-mapped-IPv6 fix above; flagged by an independent adversarial review):
-    // `::` (IPv6 unspecified/"any", the analog of 0.0.0.0, which the IPv4 branch
-    // above does block), IPv6 multicast (ff00::/8), and NAT64 (64:ff9b::/96) are
-    // not covered. Left as a follow-up hardening item rather than scope-creeping
-    // this patch.
-    return false;
-}
 export function validateHeaders(headers) {
     const allowAuth = process.env.CLAUDE_FLOW_HTTP_FETCH_ALLOW_AUTH === '1';
     const out = {};
@@ -156,7 +97,8 @@ function clampNumber(raw, defaultValue, max) {
  * dispatcher. Returns a result object (does not throw on validation failure
  * — it returns success: false with an errorCode).
  */
-export async function httpFetchExecute(input) {
+export async function httpFetchExecute(input, deps = {}) {
+    const send = deps.request ?? pinnedRequest;
     const startedAt = Date.now();
     const url = String(input.url ?? '');
     const method = String(input.method ?? 'GET').toUpperCase();
@@ -242,12 +184,13 @@ export async function httpFetchExecute(input) {
         // protocols after passing the allowlist. Every hop is validated with the
         // same rules; sensitive headers are dropped when the origin changes.
         while (true) {
-            response = await fetch(currentUrl.toString(), {
+            // Never fetch(): it resolves the hostname again on its own, so what it connects to is
+            // not what was checked. `send` connects only to addresses its DNS lookup checked.
+            response = await send(currentUrl.toString(), {
                 method: currentMethod,
                 headers,
                 body: currentMethod === 'GET' || currentMethod === 'HEAD' ? undefined : currentBody,
                 signal: controller.signal,
-                redirect: 'manual',
             });
             if (!REDIRECT_STATUSES.has(response.status))
                 break;
@@ -378,6 +321,12 @@ export async function httpFetchExecute(input) {
     }
     catch (e) {
         const msg = e instanceof Error ? e.message : String(e);
+        if (e instanceof PrivateAddressError) {
+            return {
+                success: false, status: 0, statusText: '', headers: {}, body: '', bodyTruncated: false, bytesRead: 0,
+                durationMs: Date.now() - startedAt, url: parsed.toString(), method, error: msg, errorCode: 'PRIVATE_ADDRESS',
+            };
+        }
         const aborted = msg.includes('aborted') || e?.name === 'AbortError';
         return {
             success: false,
@@ -401,7 +350,7 @@ export async function httpFetchExecute(input) {
 export const httpFetchTools = [
     {
         name: 'http_fetch',
-        description: 'ADR-164 §5.1.8 — HTTP probe primitive for business-pod ops benches (synthetic 200/500 endpoint checks, third-party status pages). Default-secure: blocks file://, ftp://, RFC-1918 / loopback / link-local hosts unless CLAUDE_FLOW_HTTP_FETCH_ALLOW_PRIVATE=1, and rejects Authorization / Cookie / X-Auth-* headers unless CLAUDE_FLOW_HTTP_FETCH_ALLOW_AUTH=1. Hard 30s timeout (60s ceiling), response truncated to 256 KB (1 MB ceiling), default User-Agent ruflo-http-fetch/1.0. Use when a pod or smoke contract needs a guarded HTTP probe — calling Node fetch() directly is wrong because it skips the URL allowlist and header sanitization that ADR-164 mandates for autopilot mode. Pair with the ops-pod bench in plugins/ruflo-business-pods/templates/ops.json (the §4.4 synthetic-endpoint test).',
+        description: 'ADR-164 §5.1.8 — HTTP probe primitive for business-pod ops benches (synthetic 200/500 endpoint checks, third-party status pages). Default-secure: blocks file://, ftp://, and RFC-1918 / loopback / link-local hosts, whether given as an address or as a name that resolves to one (checked on the connection itself, every redirect hop included), unless CLAUDE_FLOW_HTTP_FETCH_ALLOW_PRIVATE=1, and rejects Authorization / Cookie / X-Auth-* headers unless CLAUDE_FLOW_HTTP_FETCH_ALLOW_AUTH=1. Hard 30s timeout (60s ceiling), response truncated to 256 KB (1 MB ceiling), default User-Agent ruflo-http-fetch/1.0. Use when a pod or smoke contract needs a guarded HTTP probe — calling Node fetch() directly is wrong because it skips the URL allowlist and header sanitization that ADR-164 mandates for autopilot mode. Pair with the ops-pod bench in plugins/ruflo-business-pods/templates/ops.json (the §4.4 synthetic-endpoint test).',
         category: 'business-pods',
         tags: ['business-pods', 'http', 'fetch', 'adr-164', 'security', 'ops-pod'],
         inputSchema: {

package/dist/src/memory/sona-optimizer.d.ts

@@ -29,6 +29,11 @@ export interface TrajectoryOutcome {
     }>;
     feedback?: string;
     duration?: number;
+    /**
+     * ADR-511: files the task's verified fix edited (project-relative). Never keywords: they only decide which pattern a
+     * trajectory reinforces, so two wordings of one task that fixed the same file learn together.
+     */
+    anchors?: string[];
 }
 /**
  * Learned routing pattern
@@ -48,6 +53,8 @@ export interface LearnedPattern {
     lastUsed: number;
     /** Pattern creation time */
     createdAt: number;
+    /** ADR-511: files verified fixes for this pattern edited; absent in patterns saved before it. */
+    anchors?: string[];
 }
 /**
  * Routing suggestion result

package/dist/src/memory/sona-optimizer.js

@@ -28,6 +28,14 @@ const DECAY_RATE = 0.01; // Per day
 const MAX_PATTERNS = 1000;
 /** #4134: a trajectory reinforces an existing pattern of the same agent whose keyword set overlaps at least this much (Jaccard). */
 const NEIGHBOUR_MIN_JACCARD = 0.6;
+/** ADR-511: files a pattern remembers as anchors, at most. */
+const MAX_ANCHORS = 20;
+/** ADR-511: words too common in task prompts to say two tasks are alike, even when they fixed the same file. */
+const GENERIC_WORDS = new Set(['test', 'tests', 'fix', 'fixes', 'bug', 'bugs', 'run', 'make', 'find', 'check', 'confirm', 'please', 'wrong', 'issue', 'problem', 'error', 'code', 'file', 'files', 'project', 'cause', 'track', 'down', 'need', 'needs', 'some', 'something', 'again', 'npm', 'node']);
+/** ADR-511: non-generic keywords two anchor-sharing tasks must also share to reinforce one pattern. */
+const ANCHOR_MIN_SHARED = 2;
+/** Anchors as stored: lower case, path characters only, at most five per trajectory. */
+const anchorList = (raw) => Array.isArray(raw) ? [...new Set(raw.filter((a) => typeof a === 'string' && /^[a-z0-9_][a-z0-9_./-]{0,119}$/i.test(a) && !a.split('/').includes('..')).map(a => a.toLowerCase()))].slice(0, 5) : [];
 /** The routing gate in getRoutingSuggestion: confidence x matchRatio must reach this for a learned pattern to be used. */
 export const SONA_ROUTING_GATE = 0.6;
 // ============================================================================
@@ -215,6 +223,7 @@ export class SONAOptimizer {
      */
     processTrajectoryOutcome(outcome) {
         const { task, agent, success } = outcome;
+        const anchors = anchorList(outcome.anchors);
         // Extract keywords from task
         const keywords = this.extractKeywords(task);
         if (keywords.length === 0) {
@@ -232,7 +241,7 @@ export class SONAOptimizer {
         // the routing gate. Reinforce the closest existing pattern of the same agent instead.
         let reinforcedNeighbour = false;
         if (!this.patterns.has(patternKey)) {
-            const neighbour = this.findNeighbourPattern(keywords, agent);
+            const neighbour = this.findNeighbourPattern(keywords, agent, anchors);
             if (neighbour) {
                 patternKey = neighbour;
                 reinforcedNeighbour = true;
@@ -263,6 +272,13 @@ export class SONAOptimizer {
             this.failedRoutings++;
         }
         pattern.lastUsed = Date.now();
+        if (anchors.length > 0) {
+            const kept = pattern.anchors ?? [];
+            for (const a of anchors)
+                if (!kept.includes(a) && kept.length < MAX_ANCHORS)
+                    kept.push(a);
+            pattern.anchors = kept;
+        }
         // Store pattern
         this.patterns.set(patternKey, pattern);
         this.trajectoriesProcessed++;
@@ -566,20 +582,34 @@ export class SONAOptimizer {
      * `keywords` the most, if that overlap (Jaccard) reaches NEIGHBOUR_MIN_JACCARD.
      * Ties go to the more confident pattern. Linear in the pattern count (<= 1000).
      */
-    findNeighbourPattern(keywords, agent) {
+    findNeighbourPattern(keywords, agent, anchors = []) {
         const wanted = new Set(keywords);
+        // ADR-511: a keyword with a `/` names a file or directory (`src/slugify`). Two tasks that each name one and share
+        // none are about different code, however alike the rest of their wording: they never reinforce one pattern.
+        const paths = keywords.filter(k => k.includes('/'));
         let bestKey = null;
         let bestJaccard = 0;
         let bestConfidence = -1;
         for (const [key, pattern] of this.patterns) {
             if (pattern.agent !== agent)
                 continue;
+            if (paths.length > 0 && pattern.keywords.some(k => k.includes('/')) && !paths.some(k => pattern.keywords.includes(k)))
+                continue;
             let shared = 0;
-            for (const k of pattern.keywords)
-                if (wanted.has(k))
-                    shared++;
+            let distinctive = 0;
+            for (const k of pattern.keywords) {
+                if (!wanted.has(k))
+                    continue;
+                shared++;
+                if (!GENERIC_WORDS.has(k))
+                    distinctive++;
+            }
             const union = wanted.size + pattern.keywords.length - shared;
-            const jaccard = union === 0 ? 0 : shared / union;
+            let jaccard = union === 0 ? 0 : shared / union;
+            // ADR-511: a verified fix to the same file, worded differently, is the same task when the wordings also share
+            // what makes them specific (two unrelated tasks that both touched a README are not).
+            if (jaccard < NEIGHBOUR_MIN_JACCARD && distinctive >= ANCHOR_MIN_SHARED && Array.isArray(pattern.anchors) && anchors.some(a => pattern.anchors.includes(a)))
+                jaccard = NEIGHBOUR_MIN_JACCARD;
             if (jaccard >= NEIGHBOUR_MIN_JACCARD &&
                 (jaccard > bestJaccard || (jaccard === bestJaccard && pattern.confidence > bestConfidence))) {
                 bestKey = key;

package/dist/src/memory/verified-lessons.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The lessons file the learning loop writes (#4581 ADR-502, ADR-511): SONA patterns that verified outcomes trained,
+ * at or above the routing gate as lessons, repeated verified failures as cautions.
+ *
+ * ADR-511 adds what a lesson can act on: the project files the passing fixes edited, counted per pattern in the
+ * ingest ledger and named (at most three, most often first) in the lesson. A path reaches the file only if it passes
+ * `lessonFile`, the same screen the mod applies when it records and again when it reads.
+ */
+import { type HoldReason, type PatternStats } from './verified-guards.js';
+/** The SONA routing gate (sona-optimizer.ts `SONA_ROUTING_GATE`); a lesson below it never influences routing. */
+export declare const LESSON_GATE = 0.6;
+export declare const MAX_LESSONS = 20;
+/** Verified failures (and more failures than successes) before a pattern becomes a caution. */
+export declare const CAUTION_MIN_FAILURES = 2;
+/** ADR-511: files a record may carry, files a pattern counts, and files a lesson names. */
+export declare const MAX_RECORD_FILES = 5;
+export declare const MAX_PATTERN_FILES = 20;
+export declare const MAX_LESSON_FILES = 3;
+export interface Lesson {
+    readonly id: string;
+    readonly kind: 'lesson' | 'caution';
+    readonly agent: string;
+    readonly keywords: string[];
+    readonly confidence: number;
+    readonly successes: number;
+    readonly failures: number;
+    readonly evidence: string;
+    /** ADR-511: files the passing fixes edited, most often first (a lesson only). */
+    readonly files?: string[];
+}
+export interface LessonsFile {
+    version: 1;
+    gate: number;
+    generatedAt: number;
+    lessons: Lesson[];
+    /** Verified patterns still below the gate, for the cold-start progress line. */
+    belowGate: number;
+    /** Patterns at or above the gate that the anomaly gate kept out of the prompt (ADR-503 §2.4). */
+    held: Array<{
+        id: string;
+        reason: HoldReason;
+    }>;
+}
+/** What `SonaLike.exportPatterns()` returns. */
+export type PatternExport = Record<string, {
+    keywords: string[];
+    agent: string;
+    confidence: number;
+    successCount: number;
+    failureCount: number;
+}>;
+/** The ledger's view of one verified pattern that buildLessons reads. */
+export interface VerifiedPattern {
+    evidence: string;
+    at: number;
+    stats?: PatternStats;
+    /** ADR-511: edited file → verified successes that edited it. */
+    files?: Record<string, number>;
+}
+/**
+ * ADR-511: whether a path may be named in a lesson. Project-relative source files only: no absolute path, no `..`,
+ * no dot-file or dot-directory, no name that may hold a secret, no test file and no verifier config.
+ */
+export declare function lessonFile(path: unknown): path is string;
+/** A record's `files`, screened. */
+export declare const recordFiles: (raw: unknown) => string[];
+/** A ledger pattern's file counts, screened; a hostile ledger keeps nothing it should not. */
+export declare function parseFileCounts(raw: unknown): Record<string, number>;
+/** Counts one verified success's files; past the cap, the least-counted file makes room. */
+export declare function addFiles(counts: Record<string, number>, files: readonly string[]): void;
+/** The files a lesson names: most often first, ties by name, at most three. */
+export declare const topFiles: (counts: Record<string, number> | undefined) => string[];
+/** A lesson's citation: a short hash of the SONA pattern key, so the key's own text never reaches a prompt. */
+export declare const lessonId: (patternKey: string) => string;
+/**
+ * Builds the lessons file from SONA's patterns, keeping only the ones verified outcomes trained. A would-be lesson the
+ * anomaly gate holds (ADR-503 §2.4) is listed under `held` instead: it stays in SONA, never in a prompt.
+ */
+export declare function buildLessons(patterns: PatternExport, verified: Record<string, VerifiedPattern>, now: number): LessonsFile;
+//# sourceMappingURL=verified-lessons.d.ts.map