agentic-workflow-manager 3.3.1 → 3.4.0

package/dist/src/commands/ledger/index.js

@@ -47,7 +47,7 @@ function registerLedgerCommand(program) {
     });
     ledger
         .command('recurring')
-        .description('print signature clusters with count >= min (recurrence signal)')
+        .description('print recurrence clusters with count >= min (exact signature repeats and cross-reviewer convergence)')
         .option('--min <n>', 'minimum occurrences', '2')
         .option('--branch <branch>', 'override branch (default: git current branch)')
         .action((opts) => {

package/dist/src/core/export/transform.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFERENCE_LINE = void 0;
+exports.stripIntraRegistryPaths = stripIntraRegistryPaths;
 exports.claudeAiTransform = claudeAiTransform;
 // cli/src/core/export/transform.ts
 //
@@ -9,6 +10,53 @@ exports.claudeAiTransform = claudeAiTransform;
 // línea) — sin parser YAML a propósito (YAGNI, cero deps).
 const DEFERENCE_LINE = (skillName) => `In environments with AWM installed (Claude Code), defer to the registry's ${skillName} skill — this port is for environments without filesystem access.`;
 exports.DEFERENCE_LINE = DEFERENCE_LINE;
+// Paths intra-registry: resuelven en Claude Code (donde el registry está en
+// disco) y nunca en claude.ai, donde solo se sube la skill portable. Se limpian
+// en el artefacto exportado en vez de editar el SKILL.md canónico, que en Claude
+// Code sí los necesita.
+const SKILL_NAME = '[a-z0-9][a-z0-9-]*';
+const REF_FILE = '[A-Za-z0-9._-]+';
+const PATH_SRC = '(?:skills\\/' + SKILL_NAME + '\\/references\\/' + REF_FILE + '\\.md'
+    + '|skills\\/' + SKILL_NAME + '\\/SKILL\\.md)';
+/** Reconoce, en una sola pasada sobre el body ORIGINAL, tanto el caso
+ * "paréntesis cuyo único contenido es un path" (grupo 1) como el path suelto
+ * en cualquier otra posición (grupo 2). Una sola pasada evita un bug real de
+ * splicing encontrado en code review: si se borrara el paréntesis en una
+ * pasada separada, un path inmediatamente siguiente podría quedar pegado a
+ * texto que antes terminaba en `/` (el cierre de una URL, p. ej.), y el guard
+ * de "embebido en URL" (que mira el carácter previo) confundiría eso con un
+ * path genuinamente embebido. Matcheando todo en una sola pasada contra el
+ * string original, cada offset que llega a `isEmbeddedInUrl` es siempre real,
+ * nunca un artefacto de un borrado previo. */
+const PATH_OR_DROPPED_PAREN = new RegExp('([ \\t]*\\((?:see[ \\t]+)?`?' + PATH_SRC + '`?\\))' + '|' + '(`?' + PATH_SRC + '`?)', 'g');
+/** Un path precedido por `/` es el final de una URL o de un path más largo (un
+ * enlace a GitHub, por ejemplo). Esas referencias SÍ resuelven para quien lee la
+ * skill en claude.ai, así que no se tocan. */
+function isEmbeddedInUrl(haystack, matchStart, matched) {
+    const pathStart = matchStart + matched.indexOf('skills/');
+    return pathStart > 0 && haystack[pathStart - 1] === '/';
+}
+const PATH_MATCHER = new RegExp('^skills\\/(' + SKILL_NAME + ')\\/references\\/(' + REF_FILE + ')\\.md$'
+    + '|^skills\\/(' + SKILL_NAME + ')\\/SKILL\\.md$');
+function pathlessForm(p) {
+    const m = PATH_MATCHER.exec(p);
+    if (!m)
+        throw new Error(`unreachable: "${p}" matched PATH_SRC but not PATH_MATCHER — the two must stay in sync`);
+    const [, refSkill, refFile, skillOnlyName] = m;
+    if (skillOnlyName !== undefined)
+        return `the \`${skillOnlyName}\` skill`;
+    return `the \`${refSkill}\` skill's ${refFile.replace(/-/g, ' ')} reference`;
+}
+function stripIntraRegistryPaths(body) {
+    return body.replace(PATH_OR_DROPPED_PAREN, (match, parenForm, bareForm, offset) => {
+        if (isEmbeddedInUrl(body, offset, match))
+            return match;
+        if (parenForm !== undefined)
+            return '';
+        const path = bareForm.replace(/^`|`$/g, '');
+        return pathlessForm(path);
+    });
+}
 function claudeAiTransform(skillMd, skillName) {
     // \r?\n-tolerant, same rationale as readArtifactDescription in discovery.ts:
     // SKILL.md files may be CRLF-terminated and that's still valid frontmatter.
@@ -53,5 +101,7 @@ function claudeAiTransform(skillMd, skillName) {
             ? `${value.slice(0, -1)} ${deference.replace(/'/g, "''")}'`
             : `${value} ${deference}`;
     fmLines[descIdx] = `description: ${newValue}`;
-    return `---\n${fmLines.join('\n')}\n---\n${body}`;
+    // Solo el body: el frontmatter ya se editó arriba y sus campos no son prosa
+    // navegable (R2.4).
+    return `---\n${fmLines.join('\n')}\n---\n${stripIntraRegistryPaths(body)}`;
 }

package/dist/src/core/ledger/cluster.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEXICAL_AFFINITY_MIN = void 0;
+exports.normalizeTokens = normalizeTokens;
+exports.affinity = affinity;
+exports.normalizeRef = normalizeRef;
+exports.clusterEntries = clusterEntries;
+/** Palabras sin valor discriminante de identidad de defecto: se descartan antes
+ * de medir afinidad para que no inflen el score de dos hallazgos distintos. */
+const STOPWORDS = new Set([
+    'the', 'and', 'for', 'with', 'that', 'this', 'from', 'into', 'not', 'but',
+    'its', 'has', 'have', 'was', 'are', 'were', 'when', 'then', 'than', 'only',
+    'all', 'any', 'via', 'per', 'out', 'off', 'over', 'under',
+]);
+function normalizeTokens(...texts) {
+    const out = new Set();
+    for (const text of texts) {
+        for (const token of text.toLowerCase().split(/[^a-z0-9]+/)) {
+            if (token.length < 2)
+                continue;
+            if (STOPWORDS.has(token))
+                continue;
+            out.add(token);
+        }
+    }
+    return out;
+}
+/** Coeficiente de solapamiento — |A∩B| / min(|A|,|B|). Elegido sobre Jaccard
+ * porque el caso normal acá es un slug corto contra una descripción larga, y
+ * Jaccard castiga esa diferencia de longitud incluso cuando el set corto está
+ * completamente contenido en el largo. */
+function affinity(a, b) {
+    if (a.size === 0 || b.size === 0)
+        return 0;
+    let shared = 0;
+    for (const token of a)
+        if (b.has(token))
+            shared++;
+    return shared / Math.min(a.size, b.size);
+}
+/** El locus de archivo de un `ref`, o null cuando el ref no apunta a un archivo.
+ * `PR #16` devuelve null a propósito: un PR entero no es un locus de defecto, y
+ * agrupar por él fundiría todo lo hallado en una misma review. */
+function normalizeRef(ref) {
+    if (!ref)
+        return null;
+    const locus = ref.split(':')[0].trim();
+    if (!locus)
+        return null;
+    if (!locus.includes('/') && !/\.[a-z0-9]+$/i.test(locus))
+        return null;
+    return locus;
+}
+/** Umbral sin `ref` compartido: alto, porque la afinidad léxica es la única
+ * evidencia disponible y un falso positivo acá funde hallazgos de archivos
+ * distintos.
+ *
+ * Con `ref` compartido no hay umbral de ratio: alcanza **un token en común**
+ * (`score > 0`). Es deliberado y no es lo mismo que "un umbral muy bajo":
+ * compartir archivo ya es evidencia fuerte y barata de mismo locus, así que lo
+ * único que falta descartar es el par sin ninguna palabra en común — dos
+ * defectos genuinamente distintos que caen en el mismo archivo. Un ratio bajo
+ * (probamos 0.2) hacía que el caso real del issue —tres lentes, siete a nueve
+ * tokens cada una, un solo token compartido por par— cayera exactamente sobre
+ * el borde: agrupaba por casualidad aritmética, y cualquier palabra más en una
+ * descripción lo habría vuelto a romper. */
+exports.LEXICAL_AFFINITY_MIN = 0.6;
+/** Devuelve, por índice de entrada, el índice raíz de su cluster. */
+function unify(entries) {
+    const parent = entries.map((_, i) => i);
+    const find = (i) => {
+        let node = i;
+        while (parent[node] !== node) {
+            parent[node] = parent[parent[node]];
+            node = parent[node];
+        }
+        return node;
+    };
+    const union = (a, b) => {
+        const rootA = find(a);
+        const rootB = find(b);
+        // La raíz más baja gana: hace el resultado independiente del orden de
+        // comparación, y por lo tanto determinístico.
+        if (rootA !== rootB)
+            parent[Math.max(rootA, rootB)] = Math.min(rootA, rootB);
+    };
+    const tokens = entries.map((e) => normalizeTokens(e.signature, e.desc));
+    const refs = entries.map((e) => normalizeRef(e.ref));
+    for (let i = 0; i < entries.length; i++) {
+        for (let j = i + 1; j < entries.length; j++) {
+            if (entries[i].signature === entries[j].signature) {
+                union(i, j); // R1.1 — piso preservado, sin más condiciones
+                continue;
+            }
+            if (entries[i].polarity !== entries[j].polarity)
+                continue; // R1.4
+            const score = affinity(tokens[i], tokens[j]);
+            const sameFile = refs[i] !== null && refs[i] === refs[j];
+            // Mismo archivo: cualquier palabra en común alcanza (R1.2).
+            // Archivos distintos: la afinidad tiene que sostener sola (R1.3).
+            const unionable = sameFile ? score > 0 : score >= exports.LEXICAL_AFFINITY_MIN;
+            if (unionable)
+                union(i, j);
+        }
+    }
+    return entries.map((_, i) => find(i));
+}
+function clusterEntries(entries, min) {
+    const roots = unify(entries);
+    const byRoot = new Map();
+    for (let i = 0; i < entries.length; i++) {
+        const group = byRoot.get(roots[i]) ?? [];
+        group.push(entries[i]);
+        byRoot.set(roots[i], group);
+    }
+    const clusters = [];
+    for (const group of byRoot.values()) {
+        const freq = new Map();
+        for (const e of group)
+            freq.set(e.signature, (freq.get(e.signature) ?? 0) + 1);
+        const signatures = [...freq.keys()].sort();
+        // signatures viene ascendente y la comparación es estricta, así que un
+        // empate de frecuencia deja parada la primera lexicográfica (R1.8).
+        const representative = signatures.reduce((best, s) => (freq.get(s) > freq.get(best) ? s : best), signatures[0]);
+        clusters.push({
+            signature: representative,
+            count: group.length,
+            kind: signatures.length > 1 ? 'convergent' : 'exact',
+            signatures,
+            entries: group,
+        });
+    }
+    return clusters
+        .filter((c) => c.count >= min)
+        .sort((a, b) => b.count - a.count
+        || (a.kind === b.kind ? 0 : a.kind === 'convergent' ? -1 : 1)
+        || a.signature.localeCompare(b.signature));
+}

package/dist/src/core/ledger/store.js

@@ -12,6 +12,7 @@ exports.archiveLedger = archiveLedger;
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const child_process_1 = require("child_process");
+const cluster_1 = require("./cluster");
 const LEDGER_DIR = path_1.default.join('.awm', 'ledger');
 function detectBranch(cwd) {
     try {
@@ -33,6 +34,21 @@ function addEntry(cwd, entry) {
     fs_1.default.mkdirSync(path_1.default.dirname(p), { recursive: true });
     fs_1.default.appendFileSync(p, JSON.stringify(entry) + '\n', 'utf-8');
 }
+/** Required LedgerEntry fields that `cluster.ts` reads unconditionally
+ * (`signature`, `desc`, `ref` when present). A JSONL line can be syntactically
+ * valid JSON while still being shape-invalid (e.g. missing `desc`) — that's
+ * not a parse error, so it needs its own check, extending the same "skip
+ * malformed line" policy this function already applies to JSON syntax errors. */
+function isWellFormedEntry(x) {
+    if (!x || typeof x !== 'object')
+        return false;
+    const e = x;
+    return typeof e.signature === 'string'
+        && typeof e.desc === 'string'
+        && typeof e.branch === 'string'
+        && typeof e.polarity === 'string'
+        && (e.ref === undefined || typeof e.ref === 'string');
+}
 function listEntries(cwd, branch) {
     const p = ledgerPath(cwd, branch);
     if (!fs_1.default.existsSync(p))
@@ -43,23 +59,16 @@ function listEntries(cwd, branch) {
         if (!trimmed)
             continue;
         try {
-            out.push(JSON.parse(trimmed));
+            const parsed = JSON.parse(trimmed);
+            if (isWellFormedEntry(parsed))
+                out.push(parsed);
         }
         catch { /* skip malformed line */ }
     }
     return out;
 }
 function recurring(cwd, branch, min) {
-    const bySig = new Map();
-    for (const e of listEntries(cwd, branch)) {
-        const arr = bySig.get(e.signature) ?? [];
-        arr.push(e);
-        bySig.set(e.signature, arr);
-    }
-    return [...bySig.entries()]
-        .map(([signature, entries]) => ({ signature, count: entries.length, entries }))
-        .filter(c => c.count >= min)
-        .sort((a, b) => b.count - a.count);
+    return (0, cluster_1.clusterEntries)(listEntries(cwd, branch), min);
 }
 function archiveLedger(cwd, branch, label) {
     const src = ledgerPath(cwd, branch);

package/dist/tests/core/export/engine.test.js

@@ -35,7 +35,7 @@ function makeRoot() {
     fs_1.default.mkdirSync(path_1.default.join(mermaid, 'references'));
     fs_1.default.writeFileSync(path_1.default.join(mermaid, 'references/flow.md'), 'flow reference bytes');
     const ported = mk('ported', ['name: ported', 'portable: true', 'description: "Ported."']);
-    fs_1.default.writeFileSync(path_1.default.join(ported, 'port.claude-ai.md'), '---\nname: ported\ndescription: "Custom port."\n---\nOverride body, verbatim.\n');
+    fs_1.default.writeFileSync(path_1.default.join(ported, 'port.claude-ai.md'), '---\nname: ported\ndescription: "Custom port."\n---\nOverride body, verbatim, citing `skills/readiness-gate/SKILL.md` on purpose.\n');
     return root;
 }
 describe('runExport (engine end-to-end)', () => {
@@ -60,7 +60,7 @@ describe('runExport (engine end-to-end)', () => {
         expect(mermaidMd).toContain('defer to the registry');
         expect(fs_1.default.readFileSync(path_1.default.join(out, 'claude-ai/mermaid/references/flow.md'), 'utf-8')).toBe('flow reference bytes');
         const portedMd = fs_1.default.readFileSync(path_1.default.join(out, 'claude-ai/ported/SKILL.md'), 'utf-8');
-        expect(portedMd).toBe('---\nname: ported\ndescription: "Custom port."\n---\nOverride body, verbatim.\n'); // cero transforms
+        expect(portedMd).toBe('---\nname: ported\ndescription: "Custom port."\n---\nOverride body, verbatim, citing `skills/readiness-gate/SKILL.md` on purpose.\n'); // cero transforms
     });
     it('rejects an unknown target listing the valid ones', () => {
         expect(() => (0, export_1.runExport)({ name: 'dev', target: 'hermes', out, roots: [root], zip: okZip }))
@@ -101,4 +101,9 @@ describe('runExport (engine end-to-end)', () => {
             fs_1.default.rmSync(cwdTmp, { recursive: true, force: true });
         }
     });
+    it('does not rewrite paths inside a verbatim override', () => {
+        (0, export_1.runExport)({ name: 'dev', out, roots: [root], zip: okZip });
+        const portedMd = fs_1.default.readFileSync(path_1.default.join(out, 'claude-ai/ported/SKILL.md'), 'utf-8');
+        expect(portedMd).toContain('citing `skills/readiness-gate/SKILL.md` on purpose');
+    });
 });

package/dist/tests/core/export/transform.test.js

@@ -71,4 +71,81 @@ describe('claudeAiTransform', () => {
         const input = FM(['name: x', 'portable: true', 'description: "Does things." # a comment']);
         expect(() => (0, transform_1.claudeAiTransform)(input, 'x')).toThrow(/trailing content|comment/i);
     });
+    it('cleans intra-registry paths in the body', () => {
+        const md = [
+            '---',
+            'name: product-discovery',
+            'version: "1.0.0"',
+            'portable: true',
+            'description: "Explores problem space."',
+            '---',
+            'Hand off to `product-brief` (see `skills/product-brief/SKILL.md`) at the end.',
+            '',
+        ].join('\n');
+        const out = (0, transform_1.claudeAiTransform)(md, 'product-discovery');
+        expect(out).toContain('Hand off to `product-brief` at the end.');
+        expect(out).not.toContain('skills/product-brief/SKILL.md');
+    });
+    it('leaves the frontmatter block free of body rewriting', () => {
+        const md = [
+            '---',
+            'name: weird',
+            'description: "Mentions skills/readiness-gate/SKILL.md inside the description."',
+            '---',
+            'Body with no paths.',
+            '',
+        ].join('\n');
+        const out = (0, transform_1.claudeAiTransform)(md, 'weird');
+        expect(out).toContain('Mentions skills/readiness-gate/SKILL.md inside the description.');
+    });
+});
+describe('stripIntraRegistryPaths', () => {
+    it('drops a parenthetical whose only content is a see-path', () => {
+        expect((0, transform_1.stripIntraRegistryPaths)('crystallize into a `product-brief` (see `skills/product-brief/SKILL.md`) — the handoff.')).toBe('crystallize into a `product-brief` — the handoff.');
+    });
+    it('drops a bare-path parenthetical without leaving a space before the comma', () => {
+        expect((0, transform_1.stripIntraRegistryPaths)('Same discipline as `brainstorming` (see `skills/brainstorming/SKILL.md`), applied at the business level.')).toBe('Same discipline as `brainstorming`, applied at the business level.');
+    });
+    it('drops a parenthetical holding only a references path', () => {
+        expect((0, transform_1.stripIntraRegistryPaths)("conforming to the brief contract's frontmatter (`skills/readiness-gate/references/brief-contract.md`), using:")).toBe("conforming to the brief contract's frontmatter, using:");
+    });
+    it('rewrites a path in place when the parenthetical carries more text', () => {
+        expect((0, transform_1.stripIntraRegistryPaths)('the literal YAML block below (see `skills/readiness-gate/references/brief-contract.md` for the full normative rules).')).toBe("the literal YAML block below (see the `readiness-gate` skill's brief contract reference for the full normative rules).");
+    });
+    it('rewrites a bare unquoted path in prose', () => {
+        expect((0, transform_1.stripIntraRegistryPaths)('shape are normative — see skills/readiness-gate/references/brief-contract.md.')).toBe("shape are normative — see the `readiness-gate` skill's brief contract reference.");
+    });
+    it('renders a SKILL.md path as a nameless skill reference', () => {
+        expect((0, transform_1.stripIntraRegistryPaths)('invoke `skills/readiness-gate/SKILL.md` to certify it.'))
+            .toBe('invoke the `readiness-gate` skill to certify it.');
+    });
+    it('leaves a GitHub URL containing the same path untouched', () => {
+        const url = 'see https://github.com/Kodria/awm-baseline-registry/blob/main/skills/readiness-gate/SKILL.md for the source.';
+        expect((0, transform_1.stripIntraRegistryPaths)(url)).toBe(url);
+    });
+    it('leaves a markdown link whose target is a URL untouched', () => {
+        const link = '[the gate](https://github.com/Kodria/awm-baseline-registry/blob/main/skills/readiness-gate/references/brief-contract.md)';
+        expect((0, transform_1.stripIntraRegistryPaths)(link)).toBe(link);
+    });
+    it('leaves prose with no intra-registry path byte-identical', () => {
+        const body = '# Heading\n\nA body that cites `docs/plans/x.md` and nothing else.\n';
+        expect((0, transform_1.stripIntraRegistryPaths)(body)).toBe(body);
+    });
+    it('handles several paths in one body', () => {
+        expect((0, transform_1.stripIntraRegistryPaths)('hand off to `product-brief` (`skills/product-brief/SKILL.md`) then invoke `skills/readiness-gate/SKILL.md`.')).toBe('hand off to `product-brief` then invoke the `readiness-gate` skill.');
+    });
+    it('rewrites a path immediately following a dropped parenthetical, even with no separator', () => {
+        // Regression guard: a naive two-pass implementation (drop parentheticals,
+        // THEN rewrite bare paths on the already-mutated string) can splice a
+        // URL's trailing "/" directly against this path with zero separator,
+        // making the URL-embedding guard misfire and silently skip the rewrite.
+        expect((0, transform_1.stripIntraRegistryPaths)('See http://x.com/y/ (see `skills/a/SKILL.md`)skills/b/SKILL.md now.')).toBe('See http://x.com/y/the `b` skill now.');
+    });
+    it('rewrites a path that is the very first characters of the body', () => {
+        // Exercises the pathStart === 0 boundary in isEmbeddedInUrl (pathStart > 0
+        // must be false, not true, when the path opens the string) — every other
+        // test in this file has text preceding the path, so this was untested.
+        expect((0, transform_1.stripIntraRegistryPaths)('skills/readiness-gate/SKILL.md is required.'))
+            .toBe('the `readiness-gate` skill is required.');
+    });
 });

package/dist/tests/core/ledger/cluster.test.js

@@ -0,0 +1,240 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const cluster_1 = require("../../../src/core/ledger/cluster");
+describe('normalizeTokens', () => {
+    test('lowercases and splits slugs on non-alphanumeric boundaries', () => {
+        expect([...(0, cluster_1.normalizeTokens)('Validator-Skips_Agents.References')].sort())
+            .toEqual(['agents', 'references', 'skips', 'validator']);
+    });
+    test('drops tokens shorter than two characters', () => {
+        expect([...(0, cluster_1.normalizeTokens)('a b ok x')].sort()).toEqual(['ok']);
+    });
+    test('drops stopwords so they cannot inflate affinity', () => {
+        expect([...(0, cluster_1.normalizeTokens)('the gate walks only the skills')].sort())
+            .toEqual(['gate', 'skills', 'walks']);
+    });
+    test('merges tokens across every text it is given', () => {
+        expect([...(0, cluster_1.normalizeTokens)('gate-walks', 'skills dir')].sort())
+            .toEqual(['dir', 'gate', 'skills', 'walks']);
+    });
+});
+describe('affinity', () => {
+    test('is the overlap coefficient, so a contained short set scores 1', () => {
+        const short = (0, cluster_1.normalizeTokens)('validator gate');
+        const long = (0, cluster_1.normalizeTokens)('validator gate walks the skills directory only');
+        expect((0, cluster_1.affinity)(short, long)).toBe(1);
+    });
+    test('is 0 for disjoint sets', () => {
+        expect((0, cluster_1.affinity)((0, cluster_1.normalizeTokens)('alpha slug'), (0, cluster_1.normalizeTokens)('beta timeout'))).toBe(0);
+    });
+    test('is 0 when either side is empty', () => {
+        expect((0, cluster_1.affinity)(new Set(), (0, cluster_1.normalizeTokens)('alpha'))).toBe(0);
+    });
+});
+describe('normalizeRef', () => {
+    test('strips the line number and keeps the file locus', () => {
+        expect((0, cluster_1.normalizeRef)('scripts/validate-portability.mjs:41')).toBe('scripts/validate-portability.mjs');
+    });
+    test('accepts a bare filename with an extension', () => {
+        expect((0, cluster_1.normalizeRef)('split.ts:12')).toBe('split.ts');
+    });
+    test('rejects a non-file ref: a whole PR is not a defect locus', () => {
+        expect((0, cluster_1.normalizeRef)('PR #16')).toBeNull();
+    });
+    test('rejects a URL, whose pre-colon portion carries no locus', () => {
+        expect((0, cluster_1.normalizeRef)('https://github.com/Kodria/agentic-workflow/pull/15')).toBeNull();
+    });
+    test('returns null for a missing ref', () => {
+        expect((0, cluster_1.normalizeRef)(undefined)).toBeNull();
+    });
+});
+function entry(over = {}) {
+    return {
+        ts: '2026-07-25T00:00:00.000Z',
+        branch: 'feat-x',
+        phase: 'post-qa',
+        source_skill: 'post-implementation-qa',
+        polarity: 'finding',
+        class: 'logica',
+        signature: 'some-finding',
+        severity: 'important',
+        desc: 'something is wrong',
+        ref: 'src/some.ts:1',
+        ...over,
+    };
+}
+describe('clusterEntries — exact signature floor', () => {
+    test('groups identical signatures and honours min', () => {
+        const clusters = (0, cluster_1.clusterEntries)([
+            entry({ signature: 'dup', desc: 'alpha slug mismatch', ref: 'src/a.ts:1' }),
+            entry({ signature: 'dup', desc: 'alpha slug mismatch', ref: 'src/a.ts:1' }),
+            entry({ signature: 'solo', desc: 'beta timeout on retry', ref: 'src/b.ts:9' }),
+        ], 2);
+        expect(clusters).toHaveLength(1);
+        expect(clusters[0]).toMatchObject({ signature: 'dup', count: 2, kind: 'exact' });
+    });
+    test('unions identical signatures even across unrelated files and descriptions', () => {
+        const clusters = (0, cluster_1.clusterEntries)([
+            entry({ signature: 'same-slug', desc: 'alpha slug mismatch', ref: 'src/a.ts:1' }),
+            entry({ signature: 'same-slug', desc: 'beta timeout on retry', ref: 'src/b.ts:9' }),
+        ], 2);
+        expect(clusters).toHaveLength(1);
+        expect(clusters[0].count).toBe(2);
+    });
+    test('unions identical signatures regardless of polarity, as before', () => {
+        const clusters = (0, cluster_1.clusterEntries)([
+            entry({ signature: 'same-slug', polarity: 'finding' }),
+            entry({ signature: 'same-slug', polarity: 'win' }),
+        ], 2);
+        expect(clusters).toHaveLength(1);
+    });
+});
+describe('clusterEntries — convergence on a shared file', () => {
+    // El caso real del 2026-07-25: tres lentes aisladas, tres slugs distintos,
+    // un solo defecto (el gate de portabilidad recorría solo skills/).
+    const threeLenses = () => [
+        entry({
+            signature: 'validator-skips-agents-references',
+            desc: 'the portability validator never walks agents/ references',
+            ref: 'scripts/validate-portability.mjs:41',
+            source_skill: 'fidelity-lens',
+        }),
+        entry({
+            signature: 'validator-scope-skills-only',
+            desc: 'validator scope covers skills only, missing sibling trees',
+            ref: 'scripts/validate-portability.mjs:41',
+            source_skill: 'logic-lens',
+        }),
+        entry({
+            signature: 'gate-walks-skills-only',
+            desc: 'the gate walks skills and nothing else',
+            ref: 'scripts/validate-portability.mjs:58',
+            source_skill: 'robustness-lens',
+        }),
+    ];
+    test('clusters three independent lenses on one defect', () => {
+        const clusters = (0, cluster_1.clusterEntries)(threeLenses(), 2);
+        expect(clusters).toHaveLength(1);
+        expect(clusters[0].count).toBe(3);
+    });
+    test('labels the cluster convergent and lists every distinct signature', () => {
+        const clusters = (0, cluster_1.clusterEntries)(threeLenses(), 2);
+        expect(clusters[0].kind).toBe('convergent');
+        expect(clusters[0].signatures).toEqual([
+            'gate-walks-skills-only',
+            'validator-scope-skills-only',
+            'validator-skips-agents-references',
+        ]);
+    });
+    test('does NOT merge two unrelated defects that happen to share a file', () => {
+        const clusters = (0, cluster_1.clusterEntries)([
+            entry({
+                signature: 'gate-walks-skills-only',
+                desc: 'the gate walks skills and nothing else',
+                ref: 'scripts/validate-portability.mjs:58',
+            }),
+            entry({
+                signature: 'exit-code-swallowed',
+                desc: 'process exits zero after a failed assertion',
+                ref: 'scripts/validate-portability.mjs:58',
+            }),
+        ], 2);
+        expect(clusters).toEqual([]);
+    });
+    test('does NOT merge a win with a finding on the strength of a shared file', () => {
+        const clusters = (0, cluster_1.clusterEntries)([
+            entry({ signature: 'gate-walks-skills-only', desc: 'the gate walks skills only', ref: 'a.mjs:1', polarity: 'finding' }),
+            entry({ signature: 'gate-walks-skills-fix', desc: 'the gate walks skills only, now fixed', ref: 'a.mjs:1', polarity: 'win' }),
+        ], 2);
+        expect(clusters).toEqual([]);
+    });
+    test('a non-file ref contributes no clustering signal', () => {
+        const clusters = (0, cluster_1.clusterEntries)([
+            entry({ signature: 'alpha-defect', desc: 'alpha slug mismatch', ref: 'PR #16' }),
+            entry({ signature: 'beta-defect', desc: 'beta timeout on retry', ref: 'PR #16' }),
+        ], 2);
+        expect(clusters).toEqual([]);
+    });
+});
+describe('clusterEntries — lexical convergence without a shared file', () => {
+    test('clusters near-identical wording across different files', () => {
+        const clusters = (0, cluster_1.clusterEntries)([
+            entry({ signature: 'vacuous-test-asserts-nothing', desc: 'test asserts nothing meaningful', ref: 'tests/a.test.ts:3' }),
+            entry({ signature: 'vacuous-test-asserts-nothing-either', desc: 'test asserts nothing meaningful', ref: 'tests/b.test.ts:7' }),
+        ], 2);
+        expect(clusters).toHaveLength(1);
+        expect(clusters[0].kind).toBe('convergent');
+    });
+    test('leaves weakly-related findings on different files apart', () => {
+        const clusters = (0, cluster_1.clusterEntries)([
+            entry({ signature: 'validator-scope-skills-only', desc: 'validator scope covers skills', ref: 'src/a.ts:1' }),
+            entry({ signature: 'gate-walks-skills-only', desc: 'the gate walks skills', ref: 'src/b.ts:1' }),
+        ], 2);
+        expect(clusters).toEqual([]);
+    });
+    test('merges A and C transitively through B, though A and C alone would not cluster', () => {
+        const chain = [
+            entry({ signature: 'aaa-marker', desc: 'alpha beta gamma delta', ref: 'src/a.ts:1' }),
+            entry({ signature: 'bbb-marker', desc: 'beta gamma delta epsilon', ref: 'src/b.ts:1' }),
+            entry({ signature: 'ccc-marker', desc: 'gamma delta epsilon zeta', ref: 'src/c.ts:1' }),
+        ];
+        const clusters = (0, cluster_1.clusterEntries)(chain, 2);
+        expect(clusters).toHaveLength(1);
+        expect(clusters[0]).toMatchObject({ count: 3, kind: 'convergent' });
+        expect(clusters[0].signatures).toEqual(['aaa-marker', 'bbb-marker', 'ccc-marker']);
+        // Control: without the bridging entry, A and C do not satisfy the
+        // threshold on their own (affinity 0.5 < LEXICAL_AFFINITY_MIN 0.6) —
+        // proving the merge above genuinely relies on transitive closure
+        // through B, not a coincidence of the threshold being lenient.
+        const withoutBridge = (0, cluster_1.clusterEntries)([chain[0], chain[2]], 2);
+        expect(withoutBridge).toEqual([]);
+    });
+});
+describe('clusterEntries — representative and ordering', () => {
+    test('representative signature is the most frequent one', () => {
+        const clusters = (0, cluster_1.clusterEntries)([
+            entry({ signature: 'zeta-frequent', desc: 'gate walks skills only', ref: 'a.mjs:1' }),
+            entry({ signature: 'zeta-frequent', desc: 'gate walks skills only', ref: 'a.mjs:1' }),
+            entry({ signature: 'alpha-rare', desc: 'gate walks skills only, second lens', ref: 'a.mjs:1' }),
+        ], 2);
+        expect(clusters).toHaveLength(1);
+        expect(clusters[0].signature).toBe('zeta-frequent');
+        expect(clusters[0].count).toBe(3);
+    });
+    test('ties on frequency resolve to the lexicographically first signature', () => {
+        const clusters = (0, cluster_1.clusterEntries)([
+            entry({ signature: 'zeta-lens', desc: 'gate walks skills only', ref: 'a.mjs:1' }),
+            entry({ signature: 'alpha-lens', desc: 'gate walks skills only', ref: 'a.mjs:1' }),
+        ], 2);
+        expect(clusters[0].signature).toBe('alpha-lens');
+    });
+    test('sorts by count desc, then convergent before exact, then signature asc', () => {
+        const clusters = (0, cluster_1.clusterEntries)([
+            // convergent cluster of 2 on one file
+            entry({ signature: 'mid-one', desc: 'gate walks skills only', ref: 'mid.mjs:1' }),
+            entry({ signature: 'mid-two', desc: 'gate walks skills only, other lens', ref: 'mid.mjs:1' }),
+            // exact cluster of 2, unrelated
+            entry({ signature: 'exact-dup', desc: 'alpha slug mismatch', ref: 'exact.ts:1' }),
+            entry({ signature: 'exact-dup', desc: 'alpha slug mismatch', ref: 'exact.ts:1' }),
+            // exact cluster of 3, unrelated — highest count wins regardless of kind
+            entry({ signature: 'top-dup', desc: 'beta timeout on retry', ref: 'top.ts:1' }),
+            entry({ signature: 'top-dup', desc: 'beta timeout on retry', ref: 'top.ts:1' }),
+            entry({ signature: 'top-dup', desc: 'beta timeout on retry', ref: 'top.ts:1' }),
+        ], 2);
+        expect(clusters.map((c) => [c.signature, c.count, c.kind])).toEqual([
+            ['top-dup', 3, 'exact'],
+            ['mid-one', 2, 'convergent'],
+            ['exact-dup', 2, 'exact'],
+        ]);
+    });
+    test('an empty ledger yields no clusters', () => {
+        expect((0, cluster_1.clusterEntries)([], 2)).toEqual([]);
+    });
+    test('min <= 0 still returns every group, including size-1 groups', () => {
+        const solo = entry({ signature: 'lonely', desc: 'nobody else mentions this', ref: 'z.ts:1' });
+        expect((0, cluster_1.clusterEntries)([solo], 0)).toEqual([
+            { signature: 'lonely', count: 1, kind: 'exact', signatures: ['lonely'], entries: [solo] },
+        ]);
+        expect((0, cluster_1.clusterEntries)([solo], -5)).toEqual((0, cluster_1.clusterEntries)([solo], 0));
+    });
+});

package/dist/tests/core/ledger/store.test.js

@@ -54,6 +54,17 @@ describe('ledger store — add/list', () => {
         expect(got).toHaveLength(2);
         expect(got.map(e => e.signature)).toEqual(['public-fn-returns-infinity', 's2']);
     });
+    test('listEntries skips a shape-invalid (but syntactically valid) entry without throwing', () => {
+        const p = (0, store_1.ledgerPath)(cwd, 'feat-x');
+        fs_1.default.mkdirSync(path_1.default.dirname(p), { recursive: true });
+        const missingDesc = JSON.stringify({ ts: 't', branch: 'feat-x', phase: 'p', source_skill: 's', polarity: 'finding', class: 'logica', signature: 'missing-desc', severity: 'minor', ref: 'a.ts:1' });
+        const nullDesc = JSON.stringify({ ...entry(), desc: null });
+        const numericSignature = JSON.stringify({ ...entry(), signature: 42 });
+        fs_1.default.writeFileSync(p, [missingDesc, nullDesc, numericSignature, JSON.stringify(entry({ signature: 's2' }))].join('\n') + '\n');
+        const got = (0, store_1.listEntries)(cwd, 'feat-x');
+        expect(got).toHaveLength(1);
+        expect(got[0].signature).toBe('s2');
+    });
 });
 describe('ledger store — detectBranch', () => {
     test('falls back to _no-branch outside a git repo', () => {
@@ -84,10 +95,10 @@ describe('ledger store — recurring', () => {
     test('groups by signature and reports clusters with count >= min', () => {
         (0, store_1.addEntry)(cwd, entry({ signature: 'dup' }));
         (0, store_1.addEntry)(cwd, entry({ signature: 'dup' }));
-        (0, store_1.addEntry)(cwd, entry({ signature: 'solo' }));
+        (0, store_1.addEntry)(cwd, entry({ signature: 'solo', ref: 'src/other.ts:3', desc: 'pagination cursor skips a page' }));
         const clusters = (0, store_1.recurring)(cwd, 'feat-x', 2);
         expect(clusters).toHaveLength(1);
-        expect(clusters[0]).toMatchObject({ signature: 'dup', count: 2 });
+        expect(clusters[0]).toMatchObject({ signature: 'dup', count: 2, kind: 'exact' });
         expect(clusters[0].entries).toHaveLength(2);
     });
     test('respects --min: count 2 is excluded when min is 3', () => {
@@ -96,14 +107,38 @@ describe('ledger store — recurring', () => {
         expect((0, store_1.recurring)(cwd, 'feat-x', 3)).toEqual([]);
     });
     test('sorts clusters by count descending', () => {
-        (0, store_1.addEntry)(cwd, entry({ signature: 'a' }));
-        (0, store_1.addEntry)(cwd, entry({ signature: 'a' }));
-        (0, store_1.addEntry)(cwd, entry({ signature: 'b' }));
-        (0, store_1.addEntry)(cwd, entry({ signature: 'b' }));
-        (0, store_1.addEntry)(cwd, entry({ signature: 'b' }));
+        (0, store_1.addEntry)(cwd, entry({ signature: 'a', ref: 'src/a.ts:1', desc: 'alpha slug mismatch' }));
+        (0, store_1.addEntry)(cwd, entry({ signature: 'a', ref: 'src/a.ts:1', desc: 'alpha slug mismatch' }));
+        (0, store_1.addEntry)(cwd, entry({ signature: 'b', ref: 'src/b.ts:1', desc: 'beta timeout on retry' }));
+        (0, store_1.addEntry)(cwd, entry({ signature: 'b', ref: 'src/b.ts:1', desc: 'beta timeout on retry' }));
+        (0, store_1.addEntry)(cwd, entry({ signature: 'b', ref: 'src/b.ts:1', desc: 'beta timeout on retry' }));
         const clusters = (0, store_1.recurring)(cwd, 'feat-x', 2);
         expect(clusters.map(c => c.signature)).toEqual(['b', 'a']);
     });
+    test('reports independent lenses on one file as a single convergent cluster', () => {
+        (0, store_1.addEntry)(cwd, entry({
+            signature: 'validator-scope-skills-only',
+            desc: 'validator scope covers skills only',
+            ref: 'scripts/validate-portability.mjs:41',
+        }));
+        (0, store_1.addEntry)(cwd, entry({
+            signature: 'gate-walks-skills-only',
+            desc: 'the gate walks skills and nothing else',
+            ref: 'scripts/validate-portability.mjs:58',
+        }));
+        const clusters = (0, store_1.recurring)(cwd, 'feat-x', 2);
+        expect(clusters).toHaveLength(1);
+        expect(clusters[0]).toMatchObject({ count: 2, kind: 'convergent' });
+        expect(clusters[0].signatures).toEqual(['gate-walks-skills-only', 'validator-scope-skills-only']);
+    });
+    test('recurring does not crash on a shape-invalid entry mixed into an otherwise valid ledger', () => {
+        (0, store_1.addEntry)(cwd, entry({ signature: 'dup', desc: 'alpha slug mismatch', ref: 'src/a.ts:1' }));
+        (0, store_1.addEntry)(cwd, entry({ signature: 'dup', desc: 'alpha slug mismatch', ref: 'src/a.ts:1' }));
+        const p = (0, store_1.ledgerPath)(cwd, 'feat-x');
+        fs_1.default.appendFileSync(p, JSON.stringify({ ts: 't', branch: 'feat-x', phase: 'p', source_skill: 's', polarity: 'finding', class: 'logica', signature: 'no-desc', severity: 'minor', ref: 'b.ts:1' }) + '\n');
+        expect(() => (0, store_1.recurring)(cwd, 'feat-x', 2)).not.toThrow();
+        expect((0, store_1.recurring)(cwd, 'feat-x', 2)).toEqual([expect.objectContaining({ signature: 'dup', count: 2 })]);
+    });
 });
 describe('ledger store — archive', () => {
     let cwd;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-workflow-manager",
-  "version": "3.3.1",
+  "version": "3.4.0",
   "main": "dist/src/index.js",
   "bin": {
     "awm": "./dist/src/index.js"