agentic-workflow-manager 3.3.1 → 3.5.0

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/dist/tests/structural/exec-invocation-explicit-stdio.test.js

@@ -0,0 +1,94 @@
+"use strict";
+// Structural regression guard for the recurring class of bug found across
+// R1's durable-controller work (harness-retro, 2026-08-01 — r1-durable-controller
+// plan, Task 20 + post-implementation-qa): execFileSync/spawn/spawnSync calls
+// with no explicit `stdio` option inherit Node's default `inheritStderr`
+// relay, which pipes the SUBPROCESS's stderr onto the CALLING process's own
+// stderr fd. When that fd is a destroyed/broken pipe (a detached wrapper
+// whose parent already tore down its own pipes, a supervisor whose stdout
+// went away), the relay itself raises an async EPIPE with no listener,
+// which Node re-throws — silently crashing the caller before it can finish
+// its work.
+//
+// The bug recurred FIVE separate times in the same session even after the
+// first fix landed: spawnStructured's own detached-child spawn, then 4 more
+// bare execFileSync('git'/'ps'/'pgrep', ...) call sites in DIFFERENT files
+// (process.ts, lock.ts, job/index.ts, watch/index.ts, fingerprint.ts) plus a
+// bonus spawnSync('zip', ...) in pack.ts — because each fix was scoped to
+// the one call site a reviewer happened to be looking at, not the whole
+// class. This test exercises the whole class in one pass: every
+// execFileSync/spawn/spawnSync call site anywhere under cli/src must pass an
+// explicit `stdio` option (or the shared `EXEC_STDIO` constant) — so a
+// future call site added without one fails immediately instead of waiting
+// for the next EPIPE crash to be noticed.
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const SRC_ROOT = path_1.default.join(__dirname, '../../src');
+const CALLEE_NAMES = ['execFileSync', 'spawnSync', 'spawn'];
+function listTsFiles(dir) {
+    const out = [];
+    for (const entry of fs_1.default.readdirSync(dir, { withFileTypes: true })) {
+        const full = path_1.default.join(dir, entry.name);
+        if (entry.isDirectory())
+            out.push(...listTsFiles(full));
+        else if (entry.isFile() && entry.name.endsWith('.ts'))
+            out.push(full);
+    }
+    return out;
+}
+// Strips comments before scanning: JSDoc/inline comments in this codebase
+// routinely reference "spawn (...)" or "execFileSync(...)" in prose (e.g.
+// process.ts's own EPIPE-hardening comment), which would otherwise register
+// as phantom call sites. Naive block/line-comment stripping, not a full TS
+// parser — sufficient for a structural guard, and a false positive here
+// fails loud rather than silently missing a real site. The `[^:]` guard on
+// `//` avoids treating a `https://` URL in a string as a line comment.
+function stripComments(source) {
+    return source
+        .replace(/\/\*[\s\S]*?\*\//g, '')
+        .replace(/(^|[^:])\/\/.*$/gm, '$1');
+}
+// Extracts the paren-balanced argument text of every call to one of
+// CALLEE_NAMES in `source` — e.g. "execFileSync('git', [...], {...})" -> the
+// text between the outer parens. Balanced-paren scanning (not a single-line
+// regex) is required because real call sites in this repo span multiple
+// lines (e.g. process.ts's pgrep call).
+function extractCalls(rawSource) {
+    const source = stripComments(rawSource);
+    const calls = [];
+    const calleeRe = new RegExp(`\\b(${CALLEE_NAMES.join('|')})\\s*\\(`, 'g');
+    let m;
+    while ((m = calleeRe.exec(source)) !== null) {
+        const start = m.index + m[0].length; // just after the opening '('
+        let depth = 1;
+        let i = start;
+        while (i < source.length && depth > 0) {
+            if (source[i] === '(')
+                depth++;
+            else if (source[i] === ')')
+                depth--;
+            i++;
+        }
+        calls.push({ callee: m[1], args: source.slice(start, i - 1) });
+    }
+    return calls;
+}
+describe('execFileSync/spawn/spawnSync invocations — explicit stdio required (structural)', () => {
+    it('every call site under cli/src passes an explicit stdio option, never relying on Node defaults', () => {
+        const violations = [];
+        for (const file of listTsFiles(SRC_ROOT)) {
+            const source = fs_1.default.readFileSync(file, 'utf8');
+            for (const call of extractCalls(source)) {
+                const hasExplicitStdio = /\bstdio\s*:/.test(call.args) || /\bEXEC_STDIO\b/.test(call.args);
+                if (!hasExplicitStdio) {
+                    violations.push(`${path_1.default.relative(SRC_ROOT, file)}: ${call.callee}(...) has no explicit stdio option`);
+                }
+            }
+        }
+        expect(violations).toEqual([]);
+    });
+});

package/package.json

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