agentic-workflow-manager 3.3.0 → 3.4.0

package/dist/src/commands/init.js

@@ -49,6 +49,7 @@ const bundles_1 = require("../core/bundles");
 const registries_1 = require("../core/registries");
 const orchestrator_1 = require("../core/init/orchestrator");
 const steps_1 = require("../core/init/steps");
+const failure_1 = require("../core/init/failure");
 const mutation_targets_1 = require("../core/init/mutation-targets");
 const provider_facts_1 = require("../core/init/provider-facts");
 const install_transaction_1 = require("../core/install-transaction");
@@ -94,6 +95,35 @@ function renderInitOutcome(o) {
     lines.push(`status: ${status} · ${pendingCount} steps require an agent (skills above)`);
     return lines.join('\n');
 }
+// ---------------------------------------------------------------------------
+// Failure reporting
+// ---------------------------------------------------------------------------
+/**
+ * Single exit point for every failed `awm init`. Honours `--json`'s contract on
+ * the error path — the whole point of the flag for a headless bootstrap is to
+ * learn WHICH step failed — and, in human mode, renders the same evidence
+ * through the normal init dashboard instead of discarding it.
+ *
+ * stdout carries the machine-readable document (JSON mode) or the dashboard
+ * (human mode); stderr always carries the one-line summary plus the
+ * transaction verdict, so `2>&1`-free scripts still see a reason.
+ */
+function reportInitFailure(o) {
+    const payload = (0, failure_1.buildInitFailureOutput)({
+        error: o.error,
+        outcome: o.outcome,
+        transaction: o.transaction,
+    });
+    if (o.json) {
+        process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+    }
+    else if (o.outcome) {
+        process.stdout.write(renderInitOutcome(o.outcome) + '\n');
+    }
+    process.stderr.write(`awm init: ${payload.error}\n`);
+    process.stderr.write(`awm init: ${payload.transaction.note}\n`);
+    return 2;
+}
 async function runInit(opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
     const agent = opts.agent === undefined ? 'claude-code' : (0, providers_1.requireAgentTarget)(opts.agent);
@@ -125,6 +155,10 @@ async function runInit(opts = {}) {
     // and would incorrectly be flagged as a violation.
     const beforeClaudeFacts = agent === 'claude-code' ? null : (0, provider_facts_1.gatherProviderFacts)('claude-code');
     let outcome;
+    // Populated as soon as each becomes available, so the failure reporter can
+    // emit whatever evidence THIS run got far enough to produce.
+    let pipelineOutcome;
+    let transaction;
     try {
         const mergedActions = {
             ...steps_1.defaultActions,
@@ -155,7 +189,11 @@ async function runInit(opts = {}) {
             (0, config_1.savePreferences)(nextPreferences);
             (0, registries_1.seedBaselineRegistry)();
             if ((0, registries_1.listRegistries)().some((r) => !fs_1.default.existsSync(r.contentRoot))) {
-                await mergedActions.syncCache();
+                // `syncRegistries()` reports per-registry failures as RESULTS,
+                // never as throws (core/registries.ts) — swallowing them here
+                // let an unavailable registry degrade silently into some later
+                // step's failure instead of being reported as its own cause.
+                (0, registries_1.assertSyncedRegistriesUsable)((await mergedActions.syncCache()) ?? []);
             }
             const bundles = (0, bundles_1.discoverAllBundles)();
             const ctx = (0, context_1.gatherContext)({ cwd, bundles, agent });
@@ -177,8 +215,13 @@ async function runInit(opts = {}) {
                 confirmExtensions,
                 actions: mergedActions,
             });
+            pipelineOutcome = outcome;
             if (outcome.failed > 0) {
-                throw new Error('one or more init steps failed');
+                // Typed so the outcome — the only record of WHICH step failed
+                // and why — survives the rollback below and reaches the
+                // reporter. A bare Error here is what made `--json` emit
+                // nothing on the one path that most needed it.
+                throw new failure_1.InitStepsFailedError(outcome);
             }
             if (beforeClaudeFacts) {
                 (0, provider_facts_1.assertClaudeBaselinePreserved)(beforeClaudeFacts, (0, provider_facts_1.gatherProviderFacts)('claude-code'));
@@ -188,21 +231,49 @@ async function runInit(opts = {}) {
             outcome.modifiedFiles = backup.targetPaths;
         }
         catch (error) {
-            backup.rollback();
+            // Rollback is best-effort and must never mask the original failure
+            // (same policy as applyInstallPlan's own rollback loop): the
+            // operator needs the step that failed, not the restore that also did.
+            let rollbackError;
+            try {
+                backup.rollback();
+            }
+            catch (e) {
+                rollbackError = e instanceof Error ? e.message : String(e);
+            }
+            transaction = {
+                committed: false,
+                rolledBack: rollbackError === undefined,
+                transactionId: backup.transactionId,
+                restoredFiles: backup.targetPaths,
+                ...(rollbackError === undefined ? {} : { rollbackError }),
+                note: (0, failure_1.transactionNote)(rollbackError === undefined),
+            };
             throw error;
         }
     }
     catch (err) {
-        process.stderr.write(`awm init: internal error: ${err.message}\n`);
-        return 2;
+        // The typed error carries its own outcome (so it stays self-sufficient
+        // for any caller of runInit); `pipelineOutcome` covers the other way a
+        // run can fail *after* the pipeline produced one — e.g. the R19
+        // Claude-baseline assertion.
+        return reportInitFailure({
+            error: err,
+            outcome: err instanceof failure_1.InitStepsFailedError ? err.outcome : pipelineOutcome,
+            transaction,
+            json: opts.json,
+        });
     }
+    // `result` mirrors the exit code, so a consumer can branch on one field
+    // instead of correlating stdout with $?: ok → 0, degraded → 1, failed → 2.
+    const result = outcome.after.overall === 'healthy' ? 'ok' : 'degraded';
     if (opts.json) {
-        process.stdout.write(JSON.stringify(outcome, null, 2) + '\n');
+        process.stdout.write(JSON.stringify({ result, ...outcome }, null, 2) + '\n');
     }
     else {
         process.stdout.write(renderInitOutcome(outcome) + '\n');
     }
-    return outcome.after.overall === 'healthy' ? 0 : 1;
+    return result === 'ok' ? 0 : 1;
 }
 // ---------------------------------------------------------------------------
 // Extension confirmation factory
@@ -240,7 +311,7 @@ function registerInitCommand(program) {
         .option('-y, --yes', 'Skip confirmation prompts')
         .option('-a, --agent <agent>', 'Target agent (default: claude-code)')
         .option('--machine-only', 'Only run machine-level steps (skip project steps)')
-        .option('--json', 'Emit the InitOutcome as JSON')
+        .option('--json', 'Emit the InitOutcome as JSON — on success and on failure (failed steps + rollback)')
         .action(async (options) => {
         (0, paths_1.warnIfUnsupportedPlatform)((m) => console.warn(picocolors_1.default.yellow(`⚠ ${m}`)));
         const code = await runInit({

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/init/failure.js

@@ -0,0 +1,74 @@
+"use strict";
+// src/core/init/failure.ts
+//
+// Failure evidence for `awm init`.
+//
+// `awm init` is transactional: any failure rolls every write back. That part
+// was always right — what was missing is the EVIDENCE. `runInitSteps` already
+// records, per step, `{ id, action: 'failed', error }` (orchestrator.ts's
+// `wrapStep`), but commands/init.ts used to collapse the whole outcome into a
+// bare `new Error('one or more init steps failed')`, so `--json` — whose only
+// job is to emit that outcome — printed nothing at all on the exact path an
+// operator needs it: a headless cloud bootstrap that just aborted.
+//
+// `InitStepsFailedError` carries the outcome across the rollback boundary, and
+// `buildInitFailureOutput` shapes it into the JSON envelope the CLI emits.
+// The envelope is deliberately self-describing (`result`, `failedSteps`,
+// `transaction`) so a bootstrap script can branch on it without re-deriving
+// anything from prose on stderr.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InitStepsFailedError = void 0;
+exports.failedSteps = failedSteps;
+exports.transactionNote = transactionNote;
+exports.buildInitFailureOutput = buildInitFailureOutput;
+/** Only the steps that actually failed — the subset an operator needs first. */
+function failedSteps(outcome) {
+    return outcome.steps.filter((s) => s.action === 'failed');
+}
+/**
+ * Thrown when the step pipeline ran to completion but ≥1 step failed. Carries
+ * the full `InitOutcome` so the rollback path can still emit it, and builds a
+ * message that names every failed step instead of the old generic sentence.
+ */
+class InitStepsFailedError extends Error {
+    outcome;
+    constructor(outcome) {
+        const detail = failedSteps(outcome)
+            .map((s) => `${s.id}: ${s.error ?? 'no error recorded'}`)
+            .join('; ');
+        super(`one or more init steps failed — ${detail || 'no failed step recorded'}`);
+        this.name = 'InitStepsFailedError';
+        this.outcome = outcome;
+    }
+}
+exports.InitStepsFailedError = InitStepsFailedError;
+const NO_TRANSACTION_NOTE = 'init failed before a backup session was opened — nothing was written, so there was nothing to roll back.';
+/** The note explaining what a given rollback outcome means for the machine. */
+function transactionNote(rolledBack) {
+    return rolledBack
+        ? 'the transaction was NOT committed: every path in restoredFiles was restored to its pre-init state. '
+            + '`after` reflects the state observed at the end of the step pipeline, BEFORE this rollback ran.'
+        : 'the transaction was NOT committed and the rollback did not complete — see rollbackError and '
+            + 'restore manually with `awm backup restore <transactionId>`.';
+}
+function buildInitFailureOutput(o) {
+    const steps = o.outcome?.steps ?? [];
+    return {
+        result: 'failed',
+        error: o.error.message,
+        steps,
+        failedSteps: steps.filter((s) => s.action === 'failed'),
+        applied: o.outcome?.applied ?? 0,
+        pending: o.outcome?.pending ?? 0,
+        failed: o.outcome?.failed ?? 0,
+        before: o.outcome?.before ?? null,
+        after: o.outcome?.after ?? null,
+        transaction: o.transaction ?? {
+            committed: false,
+            rolledBack: false,
+            transactionId: null,
+            restoredFiles: [],
+            note: NO_TRANSACTION_NOTE,
+        },
+    };
+}

package/dist/src/core/init/steps.js

@@ -39,7 +39,7 @@ const codex_agents_1 = require("../context/strategies/codex-agents");
 // ---------------------------------------------------------------------------
 const realInjectionOrchestrator = new orchestrator_1.InjectionOrchestrator();
 exports.defaultActions = {
-    syncCache: async () => { await (0, registries_1.syncRegistries)(); },
+    syncCache: async () => (0, registries_1.syncRegistries)(),
     installHook: (o) => (0, install_1.installHook)({
         agent: o.agent,
         registryRoot: o.registryRoot,
@@ -135,14 +135,30 @@ async function stepCache(d) {
     const needsSync = !registryCache.present || registryCache.gitState === 'behind';
     if (!needsSync)
         return ok('machine.cache', 'machine', 'skipped');
+    let results;
     try {
-        await d.actions.syncCache();
-        return ok('machine.cache', 'machine', 'applied');
+        results = (await d.actions.syncCache()) ?? [];
     }
     catch (e) {
         const msg = e instanceof Error ? e.message : String(e);
         return failed('machine.cache', 'machine', msg);
     }
+    // `syncRegistries()` reports per-registry failures as RESULTS, not throws
+    // (registries.ts), so the `try` above catches none of them. Ignoring them
+    // is what let an unavailable base registry degrade silently into some
+    // later step's failure — with its own cause already gone.
+    const errors = (0, registries_1.registrySyncErrors)(results);
+    if (errors.length === 0)
+        return ok('machine.cache', 'machine', 'applied');
+    // A registry that errored and has no content on disk is unusable, and every
+    // later step that reads it will fail for a reason that no longer names this
+    // cause — so machine.cache owns it here. One that errored but still has
+    // content is stale, not broken: record it and carry on.
+    const unusable = (0, registries_1.unusableSyncedRegistries)(results);
+    if (unusable.length > 0) {
+        return failed('machine.cache', 'machine', `registry unavailable — ${(0, registries_1.describeRegistrySyncErrors)(unusable)}`);
+    }
+    return ok('machine.cache', 'machine', 'applied', `stale registries — ${(0, registries_1.describeRegistrySyncErrors)(errors)}`);
 }
 /** Step 2 – Install the session-start hook for the target agent. */
 function stepHook(d) {

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/src/core/registries.js

@@ -13,6 +13,10 @@ exports.contentRoots = contentRoots;
 exports.capabilityRoot = capabilityRoot;
 exports.validateRegistryLayout = validateRegistryLayout;
 exports.syncRegistries = syncRegistries;
+exports.registrySyncErrors = registrySyncErrors;
+exports.describeRegistrySyncErrors = describeRegistrySyncErrors;
+exports.unusableSyncedRegistries = unusableSyncedRegistries;
+exports.assertSyncedRegistriesUsable = assertSyncedRegistriesUsable;
 exports.readRegistryManifest = readRegistryManifest;
 exports.registryNameForPath = registryNameForPath;
 exports.verifyMinCliVersions = verifyMinCliVersions;
@@ -144,6 +148,46 @@ async function syncRegistries() {
     }
     return results;
 }
+/** The errored entries of a `syncRegistries()` run, in `listRegistries()` order. */
+function registrySyncErrors(results) {
+    return results
+        .filter((r) => r.action === 'error')
+        .map((r) => ({ name: r.name, error: r.error }));
+}
+/** `name: reason; name: reason` — the shape both init and stepCache report errors in. */
+function describeRegistrySyncErrors(errors) {
+    return errors.map((e) => `${e.name}: ${e.error}`).join('; ');
+}
+/**
+ * Registries that both errored during sync AND have no content on disk
+ * afterwards — i.e. genuinely unusable, as opposed to merely stale.
+ *
+ * `syncRegistries()` deliberately reports per-registry failures as results
+ * rather than throwing, so a flaky secondary registry never aborts a whole
+ * run. Callers that go on to READ registry content (init) still need to know
+ * whether what they are about to read exists: otherwise a missing registry
+ * resurfaces much later as an unrelated step's failure, with its real cause
+ * already discarded. Note that "usable" is deliberately about content on disk,
+ * not about being a healthy git clone — a seeded content root with no `.git`
+ * fails to sync every time and is still perfectly readable.
+ */
+function unusableSyncedRegistries(results) {
+    const errors = registrySyncErrors(results);
+    if (errors.length === 0)
+        return [];
+    const roots = new Map(listRegistries().map((r) => [r.name, r.contentRoot]));
+    return errors.filter((e) => {
+        const root = roots.get(e.name);
+        return root === undefined || !fs_1.default.existsSync(root);
+    });
+}
+/** `unusableSyncedRegistries` as a guard: throws naming every unusable registry. */
+function assertSyncedRegistriesUsable(results) {
+    const unusable = unusableSyncedRegistries(results);
+    if (unusable.length === 0)
+        return;
+    throw new Error(`registry sync failed and left no content on disk — ${describeRegistrySyncErrors(unusable)}`);
+}
 exports.REGISTRY_MANIFEST_NAME = 'awm-registry.json';
 function readRegistryManifest(root) {
     const file = path_1.default.join(root, exports.REGISTRY_MANIFEST_NAME);

package/dist/tests/commands/init.test.js

@@ -91,6 +91,7 @@ describe('runInit', () => {
         const parsed = JSON.parse(written);
         expect(Array.isArray(parsed.steps)).toBe(true);
         expect(parsed.after.overall).toBe('degraded');
+        expect(parsed.result).toBe('degraded'); // success envelope is self-describing too
         expect(code).toBe(1);
     });
     const prefsFile = () => path_1.default.join(process.env.AWM_HOME, 'preferences.json');
@@ -291,4 +292,85 @@ describe('runInit', () => {
         // rollback must restore its exact pre-run content, not just leave it be.
         expect(JSON.parse(fs_1.default.readFileSync(settingsPath, 'utf8'))).toEqual({ pristine: true, unrelated: 'keep' });
     });
+    // -----------------------------------------------------------------------
+    // Failure evidence — `--json` must honour its contract on the ERROR path
+    // -----------------------------------------------------------------------
+    describe('failure evidence', () => {
+        let errSpy;
+        beforeEach(() => {
+            errSpy = jest.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        });
+        afterEach(() => errSpy.mockRestore());
+        const stdout = () => writeSpy.mock.calls.map((c) => c[0]).join('');
+        const stderr = () => errSpy.mock.calls.map((c) => c[0]).join('');
+        /** InitActions whose `machine.hook` step blows up inside the step pipeline. */
+        function actionsWithFailingHook() {
+            const actions = fakeActions([]);
+            actions.installHook = () => { throw new Error('hook boom'); };
+            return actions;
+        }
+        it('--json emits parseable JSON carrying the failed step id and error', async () => {
+            const { runInit } = require('../../src/commands/init');
+            const code = await runInit({
+                cwd: tmpHome,
+                yes: true,
+                json: true,
+                actions: actionsWithFailingHook(),
+            });
+            expect(code).not.toBe(0);
+            expect(code).toBe(2);
+            const parsed = JSON.parse(stdout());
+            expect(parsed.result).toBe('failed');
+            const failedStep = parsed.steps.find((s) => s.action === 'failed');
+            expect(failedStep.id).toBe('machine.hook');
+            expect(failedStep.error).toBe('hook boom');
+            expect(parsed.failedSteps).toEqual([failedStep]);
+            expect(parsed.failed).toBe(1);
+            // The top-level message names the step too — no generic "internal error".
+            expect(parsed.error).toContain('machine.hook');
+            expect(parsed.error).toContain('hook boom');
+            // `before` is the pre-run snapshot the issue asks for.
+            expect(parsed.before.results.length).toBeGreaterThan(0);
+        });
+        it('--json reports the transaction as not committed and rolled back', async () => {
+            const { runInit } = require('../../src/commands/init');
+            await runInit({ cwd: tmpHome, yes: true, json: true, actions: actionsWithFailingHook() });
+            const { transaction } = JSON.parse(stdout());
+            expect(transaction.committed).toBe(false);
+            expect(transaction.rolledBack).toBe(true);
+            expect(typeof transaction.transactionId).toBe('string');
+            expect(Array.isArray(transaction.restoredFiles)).toBe(true);
+            expect(transaction.note).toBeTruthy();
+            // The backup manifest on disk agrees: nothing was committed.
+            const { listBackups } = require('../../src/core/install-transaction');
+            const backups = listBackups();
+            expect(backups.length).toBeGreaterThan(0);
+            expect(backups.every((b) => b.committed)).toBe(false);
+            // …and the run really did not persist anything.
+            expect(fs_1.default.existsSync(prefsFile())).toBe(false);
+        });
+        it('--json still emits a failure envelope when init fails before the step pipeline', async () => {
+            const actions = fakeActions([]);
+            actions.syncCache = async () => { throw new Error('registry unreachable'); };
+            const { runInit } = require('../../src/commands/init');
+            const code = await runInit({ cwd: tmpHome, yes: true, json: true, actions });
+            expect(code).toBe(2);
+            const parsed = JSON.parse(stdout());
+            expect(parsed.result).toBe('failed');
+            expect(parsed.error).toContain('registry unreachable');
+            expect(parsed.steps).toEqual([]);
+            expect(parsed.before).toBeNull();
+            expect(parsed.transaction.committed).toBe(false);
+        });
+        it('human mode renders the failed outcome instead of swallowing it', async () => {
+            const { runInit } = require('../../src/commands/init');
+            const code = await runInit({ cwd: tmpHome, yes: true, actions: actionsWithFailingHook() });
+            expect(code).toBe(2);
+            expect(stdout()).toContain('AWM · init');
+            expect(stdout()).toContain('machine.hook');
+            expect(stdout()).toContain('hook boom');
+            expect(stderr()).toContain('machine.hook');
+            expect(stderr()).toContain('hook boom');
+        });
+    });
 });

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/init/steps-registry-sync.test.js

@@ -0,0 +1,109 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// stepCache vs. syncRegistries()'s RESULT-shaped failures.
+//
+// `syncRegistries()` never throws on a per-registry failure — it returns
+// `{ action: 'error', error }` for that registry and keeps going. stepCache
+// used to `await` it and report a blanket 'applied', so a registry that never
+// landed on disk degraded silently into some later step's failure with its own
+// cause already gone.
+//
+// Isolated in its own file (not steps.test.ts) because these assertions reach
+// `listRegistries()`, which resolves AWM_HOME at module require time — the env
+// override therefore has to happen before the module is required, which means
+// `jest.resetModules()` + `require`, not a static import.
+const fs_1 = __importDefault(require("fs"));
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+describe('stepCache — registry sync error results', () => {
+    let tmpHome;
+    let originalHome;
+    let originalAwmHome;
+    beforeEach(() => {
+        tmpHome = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-stepcache-'));
+        originalHome = process.env.HOME;
+        originalAwmHome = process.env.AWM_HOME;
+        process.env.HOME = tmpHome;
+        process.env.AWM_HOME = path_1.default.join(tmpHome, '.awm');
+        jest.resetModules();
+    });
+    afterEach(() => {
+        fs_1.default.rmSync(tmpHome, { recursive: true, force: true });
+        if (originalHome === undefined)
+            delete process.env.HOME;
+        else
+            process.env.HOME = originalHome;
+        if (originalAwmHome === undefined)
+            delete process.env.AWM_HOME;
+        else
+            process.env.AWM_HOME = originalAwmHome;
+    });
+    const awmHome = () => process.env.AWM_HOME;
+    /** Declares `names` in registries.json; creates a content root only for `withContent`. */
+    function configureRegistries(names, withContent) {
+        fs_1.default.mkdirSync(awmHome(), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(awmHome(), 'registries.json'), JSON.stringify(names.map((name) => ({ name, remote: `https://example.com/${name}.git` })), null, 2));
+        for (const name of withContent) {
+            const skills = path_1.default.join(awmHome(), 'registries', name, 'skills');
+            fs_1.default.mkdirSync(skills, { recursive: true });
+            fs_1.default.writeFileSync(path_1.default.join(skills, 'placeholder.md'), '# placeholder\n');
+        }
+    }
+    /** InitDeps just complete enough for stepCache: a machine with no registry cache yet. */
+    function deps(results) {
+        const ctx = {
+            machine: {
+                registryCache: { present: false },
+                hook: { present: true, degraded: false },
+                devCore: { present: true, brokenLinks: [] },
+                ambient: { wanted: [], installed: [] },
+                contextInjection: [],
+                globalSkills: { valid: [], repairable: [], dead: [] },
+            },
+            project: null,
+        };
+        const actions = { syncCache: async () => results };
+        return {
+            cwd: tmpHome, ctx, bundles: [], agent: 'claude-code', enabledAgents: ['claude-code'],
+            installMethod: 'symlink', registryRoot: '', contentDir: '', sensorPacksRoot: '',
+            confirmExtensions: async (p) => p, actions,
+        };
+    }
+    async function run(results) {
+        const { stepCache } = require('../../../src/core/init/steps');
+        return stepCache(deps(results));
+    }
+    it('fails, naming the registry, when a sync error left no content on disk', async () => {
+        configureRegistries(['baseline'], []);
+        const r = await run([{ name: 'baseline', action: 'error', error: 'could not clone' }]);
+        expect(r.action).toBe('failed');
+        expect(r.error).toContain('baseline');
+        expect(r.error).toContain('could not clone');
+    });
+    it('stays applied but records the error when content is already on disk', async () => {
+        configureRegistries(['baseline'], ['baseline']);
+        const r = await run([{ name: 'baseline', action: 'error', error: 'pull timed out' }]);
+        expect(r.action).toBe('applied');
+        expect(r.detail).toContain('baseline');
+        expect(r.detail).toContain('pull timed out');
+    });
+    it('fails on a secondary registry that never landed, even when the base one synced', async () => {
+        configureRegistries(['baseline', 'documentation'], ['baseline']);
+        const r = await run([
+            { name: 'baseline', action: 'pulled', version: 'v1.0.0' },
+            { name: 'documentation', action: 'error', error: 'host unreachable' },
+        ]);
+        expect(r.action).toBe('failed');
+        expect(r.error).toContain('documentation');
+        expect(r.error).not.toContain('baseline');
+    });
+    it('reports applied with no detail when every registry synced', async () => {
+        configureRegistries(['baseline'], ['baseline']);
+        const r = await run([{ name: 'baseline', action: 'pulled', version: 'v1.0.0' }]);
+        expect(r.action).toBe('applied');
+        expect(r.detail).toBeUndefined();
+    });
+});

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.0",
+  "version": "3.4.0",
   "main": "dist/src/index.js",
   "bin": {
     "awm": "./dist/src/index.js"