agentic-workflow-manager 4.1.0 → 5.0.0

package/dist/src/commands/init.js

@@ -270,8 +270,20 @@ async function runInit(opts = {}) {
             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.
+    // `result` distinguishes `ok` from `degraded` in the JSON; the EXIT CODE does
+    // not, on purpose (D-008).
+    //
+    // `degraded` used to exit `1`. It does not mean init failed — it means the
+    // harness still has `pending` steps, which is the NORMAL outcome of a first run:
+    // `CONSTITUTION.md` and `AGENTS.md` are written by an agent session, not by the
+    // CLI. So a run where nothing broke reported failure, and `awm init --yes && …`
+    // died under `set -e` — in the one command whose entire job is bootstrapping a
+    // script. Three independent readers called it a bug before it was one; the docs
+    // had grown a warning box asking people to ignore the exit code.
+    //
+    // The exit code now answers "did init do its job?". "Is the harness fully
+    // healthy?" is `awm doctor`'s question, and `result` still carries it here for
+    // any consumer that wants to branch on it.
     const result = outcome.after.overall === 'healthy' ? 'ok' : 'degraded';
     if (opts.json) {
         process.stdout.write(JSON.stringify({ result, ...outcome }, null, 2) + '\n');
@@ -279,7 +291,7 @@ async function runInit(opts = {}) {
     else {
         process.stdout.write(renderInitOutcome(outcome) + '\n');
     }
-    return result === 'ok' ? 0 : 1;
+    return 0;
 }
 // ---------------------------------------------------------------------------
 // Extension confirmation factory

package/dist/src/core/diagnostics/context.js

@@ -16,6 +16,7 @@ const status_1 = require("../../commands/hooks/status");
 const profile_1 = require("../profile");
 const bundles_1 = require("../bundles");
 const skill_integrity_1 = require("../skill-integrity");
+const artifact_state_1 = require("../artifact-state");
 const paths_1 = require("../paths");
 const provider_checks_1 = require("./provider-checks");
 // Estado de un artefacto en <dir>/<skill>: link vivo / symlink colgante / ausente.
@@ -250,10 +251,21 @@ function gatherMachine(bundles, agent = 'claude-code', projectRoot) {
         ambient: { wanted, installed },
         contextInjection: gatherContextInjection(),
         globalSkills: skillsDir !== null
-            ? (0, skill_integrity_1.classifySkillLinks)(skillsDir, (0, registries_1.contentRoots)())
-            : { valid: [], repairable: [], dead: [] },
+            ? (0, skill_integrity_1.classifySkillLinks)(skillsDir, (0, registries_1.contentRoots)(), (0, skill_integrity_1.managedLinkTargets)(safeReadArtifactState()))
+            : { valid: [], repairable: [], dead: [], usurped: [] },
     };
 }
+/** `readArtifactState` tira si el JSON esta roto — correcto para un comando que va a
+ *  ESCRIBIR sobre ese estado, inaceptable para uno que solo diagnostica. Aca degrada a
+ *  "sin ledger": se pierde la deteccion de usurpaciones, no el resto del reporte. */
+function safeReadArtifactState() {
+    try {
+        return (0, artifact_state_1.readArtifactState)();
+    }
+    catch {
+        return [];
+    }
+}
 function gatherProject(root, bundles, agent = 'claude-code') {
     const profile = (0, profile_1.readProfile)(root);
     const profilePresent = fs_1.default.existsSync(path_1.default.join(root, '.awm', 'profile.json'));
@@ -294,7 +306,12 @@ function gatherContext(opts = {}) {
     const agent = opts.agent ?? 'claude-code';
     const root = (0, profile_1.findProjectRoot)(cwd);
     const agents = opts.agents ?? [agent];
-    const scanSkills = opts.scanSkills ?? ((dir) => (0, skill_integrity_1.classifySkillLinks)(dir, (0, registries_1.contentRoots)()));
+    // El ledger se lee UNA vez por corrida y se comparte con todos los dirs escaneados:
+    // es lo unico que distingue "el usuario puso este directorio" de "algo reemplazo
+    // nuestro symlink". Best-effort — un ledger ausente o corrupto degrada a "no puedo
+    // detectar usurpaciones", nunca revienta un comando de diagnostico.
+    const managed = (0, skill_integrity_1.managedLinkTargets)(safeReadArtifactState());
+    const scanSkills = opts.scanSkills ?? ((dir) => (0, skill_integrity_1.classifySkillLinks)(dir, (0, registries_1.contentRoots)(), managed));
     return {
         machine: gatherMachine(bundles, agent, root ?? undefined),
         project: root ? gatherProject(root, bundles, agent) : null,

package/dist/src/core/diagnostics/provider-checks.js

@@ -108,13 +108,20 @@ function skillsGlobalCheck(dir, owners, integrity, renderer) {
     }
     const shared = owners.length > 1;
     const broken = integrity.repairable.length + integrity.dead.length;
+    // Usurpado ≠ roto: el link no cuelga, DESAPARECIO — otro instalador dejo un
+    // directorio real con el mismo nombre encima. El agente carga esa skill, no la
+    // nuestra, y hasta que esto se reporto el scan solo miraba symlinks, asi que el
+    // caso era literalmente invisible y `overall` decia `healthy`. No se auto-repara:
+    // borrar un directorio real con contenido de un tercero es destructivo y necesita
+    // que lo pida una persona.
+    const usurped = integrity.usurped.length;
     // Broken links are checked BEFORE shared: 'shared' is a non-degrading/OK state
     // (see checks.ts's DEGRADING_PROVIDER_STATES), so if it were set unconditionally
     // for a shared dir it would silently mask real broken/dead symlinks — a green
     // checkmark next to "N broken links → repair-global-skills" would contradict its
     // own trailing text, and `overall` would never degrade despite real breakage.
     let state;
-    if (broken > 0) {
+    if (broken > 0 || usurped > 0) {
         state = 'broken';
     }
     else if (shared) {
@@ -131,8 +138,18 @@ function skillsGlobalCheck(dir, owners, integrity, renderer) {
         state,
         target: dir,
         owners: shared ? owners : undefined,
-        detail: broken > 0 ? `${broken} broken links` : undefined,
-        remediationCode: broken > 0 ? 'repair-global-skills' : undefined,
+        detail: [
+            broken > 0 ? `${broken} broken links` : null,
+            usurped > 0
+                ? `${usurped} replaced by non-AWM content (${integrity.usurped.join(', ')})`
+                : null,
+        ].filter(Boolean).join('; ') || undefined,
+        // Una usurpacion NO la arregla `repair-global-skills` (solo toca symlinks
+        // colgantes), asi que ofrecer ese remedio seria mandar al usuario a un comando
+        // que no cambia nada. Reinstalar el bundle es lo que la resuelve.
+        remediationCode: usurped > 0
+            ? 'reinstall-usurped-skills'
+            : broken > 0 ? 'repair-global-skills' : undefined,
     };
 }
 /** R8: verify the Codex `.toml` agents this run's renderer would have produced still parse. */
@@ -334,7 +351,8 @@ function gatherProviderChecks(agents, scanSkills, projectRoot) {
         const provider = (0, providers_1.providerFor)(agent);
         const dir = provider.skill.global;
         const owners = (dir !== null ? ownersByDir.get(dir) : undefined) ?? [agent];
-        const integrity = (dir !== null ? scansByDir.get(dir) : undefined) ?? { valid: [], repairable: [], dead: [] };
+        const integrity = (dir !== null ? scansByDir.get(dir) : undefined)
+            ?? { valid: [], repairable: [], dead: [], usurped: [] };
         const checks = [
             binaryVersionCheck(agent),
             skillsGlobalCheck(dir, owners, integrity, provider.skill.renderer),

package/dist/src/core/skill-integrity.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.managedLinkTargets = managedLinkTargets;
 exports.classifySkillLinks = classifySkillLinks;
 exports.repairSkillLinks = repairSkillLinks;
 exports.reconcileAllSkillLinks = reconcileAllSkillLinks;
@@ -19,12 +20,34 @@ function findRegistrySkillPath(registryContentDirs, name) {
     }
     return null;
 }
+/** Normaliza una ruta para comparar contra el ledger: absoluta siempre, y en
+ *  Windows tambien case-insensitive, porque NTFS lo es y el ledger guarda la
+ *  ruta con el casing que tuvo al instalarse, no el que tiene al leerse. */
+function pathKey(p) {
+    const resolved = path_1.default.resolve(p);
+    return (0, paths_1.isWindowsNative)() ? resolved.toLowerCase() : resolved;
+}
+/** Targets que el ledger de artefactos declara instalados con el renderer `link`,
+ *  normalizados con `pathKey` para comparar contra rutas del filesystem.
+ *
+ *  Solo `link`: para un renderer que produce archivos reales (`cursor-mdc`,
+ *  `copilot-instructions`) "no es un symlink" es lo esperado, no una usurpacion. */
+function managedLinkTargets(records) {
+    return new Set(records.filter((r) => r.renderer === 'link').map((r) => pathKey(r.targetPath)));
+}
 /** Clasifica cada entrada de `skillsDir` (read-only, no muta nada).
  *  Agnostico al alcance: `skillsDir` es global (`provider.skill.global`) o de
  *  proyecto (`<projectRoot>/<provider.skill.local>`) — el nombre decia "Global" y
- *  eso basto para que nadie lo apuntara nunca a un dir de proyecto. */
-function classifySkillLinks(skillsDir, registryContentDirs) {
-    const out = { valid: [], repairable: [], dead: [] };
+ *  eso basto para que nadie lo apuntara nunca a un dir de proyecto.
+ *
+ *  `managedTargets` (opcional, ver `managedLinkTargets`) es lo que distingue
+ *  "un directorio que el usuario puso ahi" de "un directorio que reemplazo un
+ *  link nuestro". Sin el, el scan solo mira symlinks y una usurpacion es
+ *  literalmente invisible: `awm doctor` reporta `healthy` mientras el agente
+ *  carga la skill de otro. Por defecto vacio, para que los llamadores que no
+ *  tienen ledger a mano conserven el comportamiento anterior. */
+function classifySkillLinks(skillsDir, registryContentDirs, managedTargets = new Set()) {
+    const out = { valid: [], repairable: [], dead: [], usurped: [] };
     let entries;
     try {
         entries = fs_1.default.readdirSync(skillsDir);
@@ -41,8 +64,13 @@ function classifySkillLinks(skillsDir, registryContentDirs) {
         catch {
             continue;
         }
-        if (!lst.isSymbolicLink())
-            continue; // dirs/archivos reales no son nuestro problema
+        if (!lst.isSymbolicLink()) {
+            // Un dir/archivo real que puso el usuario no es nuestro problema. Uno
+            // que el ledger declara nuestro SI lo es — ahi hubo un reemplazo.
+            if (managedTargets.has(pathKey(p)))
+                out.usurped.push(name);
+            continue;
+        }
         if (fs_1.default.existsSync(p)) {
             out.valid.push(name);
             continue;

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

@@ -109,14 +109,17 @@ describe('runInit', () => {
             expect(caveatCalls).toHaveLength(0);
         });
     });
-    it('returns exit 1 on a bare HOME and never prompts with --yes (cache stubbed)', async () => {
+    it('returns exit 0 on a bare HOME and never prompts with --yes (cache stubbed)', async () => {
         const { runInit } = require('../../src/commands/init');
         const code = await runInit({
             cwd: tmpHome,
             yes: true,
             actions: { syncCache: async () => { }, installHook: () => ({ status: 'installed' }) },
         });
-        expect(code).toBe(1); // cache/hook/devCore siguen ausentes (syncCache no-op) → degradado
+        // Degradado (cache/hook/devCore siguen ausentes con syncCache no-op) pero NADA
+        // fallo, y el exit code de `init` responde por init, no por la salud del
+        // harness — ver D-008. Esto salia 1 y rompia `awm init --yes && …` bajo `set -e`.
+        expect(code).toBe(0);
     });
     it('--json emits a parseable InitOutcome', async () => {
         const { runInit } = require('../../src/commands/init');
@@ -131,7 +134,10 @@ describe('runInit', () => {
         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);
+        // El exit code deja de duplicar `result`: la distincion ok/degradado sigue
+        // disponible para quien la quiera, en el campo, no en `$?` (D-008).
+        expect(parsed.failed).toBe(0);
+        expect(code).toBe(0);
     });
     const prefsFile = () => path_1.default.join(process.env.AWM_HOME, 'preferences.json');
     const readPreferences = () => JSON.parse(fs_1.default.readFileSync(prefsFile(), 'utf-8'));
@@ -239,6 +245,40 @@ describe('runInit', () => {
             .toEqual(['claude-code', 'codex', 'opencode']);
     });
     // -----------------------------------------------------------------------
+    // D-008 — el exit code de `init` responde por init, no por la salud del harness
+    // -----------------------------------------------------------------------
+    //
+    // El contrato entero en un solo lugar, porque el sitio que lo rompia era el
+    // ausente: ningun test preguntaba "¿un script puede encadenar `awm init &&`?".
+    // Habia dos assertions de `toBe(1)`, y las dos *documentaban* el bug en vez de
+    // detenerlo. Tres lectores independientes lo reportaron como fallo antes de que
+    // lo fuera, y la doc habia crecido un recuadro pidiendo ignorar el exit code.
+    it('a degraded-but-successful run exits 0, so `awm init && next` survives set -e', async () => {
+        const { runInit } = require('../../src/commands/init');
+        const code = await runInit({
+            cwd: tmpHome,
+            yes: true,
+            json: true,
+            actions: { syncCache: async () => { }, installHook: () => ({ status: 'installed' }) },
+        });
+        const parsed = JSON.parse(writeSpy.mock.calls.map((c) => c[0]).join(''));
+        // Las tres afirmaciones juntas son el punto: degradado, sin nada fallado, exit 0.
+        // Cualquiera de las tres sola se puede satisfacer sin el fix.
+        expect(parsed.result).toBe('degraded');
+        expect(parsed.failed).toBe(0);
+        expect(code).toBe(0);
+    });
+    it('still refuses with exit 2 when a gate rejects — 0 does not mean "always succeed"', async () => {
+        const { runInit } = require('../../src/commands/init');
+        const code = await runInit({
+            cwd: tmpHome,
+            agent: 'codex',
+            yes: true,
+            assertProviderSupported: () => { throw new Error('requires Codex >= 0.145.0'); },
+        });
+        expect(code).toBe(2);
+    });
+    // -----------------------------------------------------------------------
     // Step 1 — gate ordering, backup/rollback atomicity, Codex/Claude coexistence
     // -----------------------------------------------------------------------
     it('gates Codex before preferences or provider writes', async () => {

package/dist/tests/core/diagnostics/checks.test.js

@@ -8,7 +8,7 @@ function healthyMachine() {
         devCore: { present: true, brokenLinks: [] },
         ambient: { wanted: [], installed: [] },
         contextInjection: [],
-        globalSkills: { valid: [], repairable: [], dead: [] },
+        globalSkills: { valid: [], repairable: [], dead: [], usurped: [] },
     };
 }
 function healthyProject() {
@@ -173,12 +173,12 @@ describe('machineChecks — global skill integrity', () => {
         };
     }
     it('ok when no broken global skill links', () => {
-        const report = (0, checks_1.runChecks)(machineCtx({ valid: ['a'], repairable: [], dead: [] }));
+        const report = (0, checks_1.runChecks)(machineCtx({ valid: ['a'], repairable: [], dead: [], usurped: [] }));
         const row = report.results.find((r) => r.id === 'machine.globalSkills');
         expect(row?.status).toBe('ok');
     });
     it('warns with awm init remedy when there are broken links', () => {
-        const report = (0, checks_1.runChecks)(machineCtx({ valid: ['a'], repairable: ['b'], dead: ['c'] }));
+        const report = (0, checks_1.runChecks)(machineCtx({ valid: ['a'], repairable: ['b'], dead: ['c'], usurped: [] }));
         const row = report.results.find((r) => r.id === 'machine.globalSkills');
         expect(row?.status).toBe('warn');
         expect(row?.detail).toContain('2'); // 1 repairable + 1 dead

package/dist/tests/core/diagnostics/context.test.js

@@ -240,7 +240,7 @@ describe('gatherContext — providers matrix (Task 9)', () => {
             process.env.AWM_HOME = originalAwmHome;
     });
     function healthySharedSkills() {
-        return { valid: ['development-process'], repairable: [], dead: [] };
+        return { valid: ['development-process'], repairable: [], dead: [], usurped: [] };
     }
     it('reports shared skills for both owners without scanning twice', () => {
         // OpenCode and Codex both read/write ~/.agents/skills (providers/index.ts) —
@@ -252,7 +252,7 @@ describe('gatherContext — providers matrix (Task 9)', () => {
         expect(report.providers.every((provider) => provider.checks.some((check) => check.state === 'shared'))).toBe(true);
     });
     it('marks skills.global healthy (not shared) for a single unshared provider', () => {
-        const scan = jest.fn(() => ({ valid: [], repairable: [], dead: [] }));
+        const scan = jest.fn(() => ({ valid: [], repairable: [], dead: [], usurped: [] }));
         const { gatherContext } = require('../../../src/core/diagnostics/context');
         const report = gatherContext({ cwd: tmpHome, bundles: [], agents: ['claude-code'], scanSkills: scan });
         expect(scan).toHaveBeenCalledTimes(1);

package/dist/tests/core/diagnostics/provider-checks.test.js

@@ -177,7 +177,7 @@ describe('gatherProviderChecks — shared skills.global does not mask broken lin
         const { computeProviderOverall } = require('../../../src/core/diagnostics/checks');
         // OpenCode and Codex share ~/.agents/skills (providers/index.ts). Stub the
         // scan to report 2 broken/dead links on that shared directory.
-        const scanSkills = jest.fn(() => ({ valid: ['ok-skill'], repairable: ['stale-skill'], dead: ['ghost-skill'] }));
+        const scanSkills = jest.fn(() => ({ valid: ['ok-skill'], repairable: ['stale-skill'], dead: ['ghost-skill'], usurped: [] }));
         const ctx = gatherContext({ cwd: tmpHome, bundles: [], agents: ['opencode', 'codex'], scanSkills });
         expect(scanSkills).toHaveBeenCalledTimes(1);
         for (const provider of ctx.providers) {
@@ -192,7 +192,7 @@ describe('gatherProviderChecks — shared skills.global does not mask broken lin
     it('still reports shared (healthy, non-degrading) when the shared dir has no broken links', () => {
         const { gatherContext } = require('../../../src/core/diagnostics/context');
         const { computeProviderOverall } = require('../../../src/core/diagnostics/checks');
-        const scanSkills = jest.fn(() => ({ valid: ['ok-skill'], repairable: [], dead: [] }));
+        const scanSkills = jest.fn(() => ({ valid: ['ok-skill'], repairable: [], dead: [], usurped: [] }));
         const ctx = gatherContext({ cwd: tmpHome, bundles: [], agents: ['opencode', 'codex'], scanSkills });
         for (const provider of ctx.providers) {
             const skillsCheck = provider.checks.find((c) => c.id === 'skills.global');
@@ -237,7 +237,7 @@ describe('gatherProviderChecks — agents.native reports broken on a malformed C
         fs_1.default.mkdirSync(agentsDir, { recursive: true });
         fs_1.default.writeFileSync(path_1.default.join(agentsDir, 'development-process.toml'), 'name = "development-process"\n# missing the developer_instructions key entirely\n');
         const { gatherContext } = require('../../../src/core/diagnostics/context');
-        const scanSkills = jest.fn(() => ({ valid: [], repairable: [], dead: [] }));
+        const scanSkills = jest.fn(() => ({ valid: [], repairable: [], dead: [], usurped: [] }));
         const ctx = gatherContext({ cwd: tmpHome, bundles: [], agents: ['codex'], scanSkills });
         const codex = ctx.providers.find((p) => p.id === 'codex');
         const agentsNative = codex.checks.find((c) => c.id === 'agents.native');

package/dist/tests/core/diagnostics/provider-tier.test.js

@@ -51,7 +51,7 @@ describe('contextGlobalCheck — scope-aware (Task 4.4 / deferred Task 4.2 findi
         return root;
     }
     function scanSkillsStub() {
-        return jest.fn(() => ({ valid: [], repairable: [], dead: [] }));
+        return jest.fn(() => ({ valid: [], repairable: [], dead: [], usurped: [] }));
     }
     beforeEach(() => {
         tmpHome = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-provider-tier-home-'));
@@ -177,7 +177,7 @@ describe('skillsGlobalCheck — renderer-aware (Task 4.4 / deferred Task 4.3 fin
         // classifySkillLinks only ever sees symlinks (`if (!lst.isSymbolicLink()) continue;`)
         // — a real scan over rulesDir would find nothing here either. Stubbed explicitly so the
         // test proves the FIX (renderer-gating), not an accident of what classifySkillLinks does.
-        const scanSkills = jest.fn(() => ({ valid: [], repairable: [], dead: [] }));
+        const scanSkills = jest.fn(() => ({ valid: [], repairable: [], dead: [], usurped: [] }));
         const { gatherProviderChecks } = require('../../../src/core/diagnostics/provider-checks');
         const facts = gatherProviderChecks(['cursor'], scanSkills);
         const skillsCheck = facts[0].checks.find((c) => c.id === 'skills.global');
@@ -216,7 +216,7 @@ describe('skillsGlobalCheck — renderer-aware (Task 4.4 / deferred Task 4.3 fin
         });
         const rulesDir = path_1.default.join(tmpHome, '.cursor/rules');
         expect(fs_1.default.existsSync(path_1.default.join(rulesDir, 'using-awm.mdc'))).toBe(true);
-        const scanSkills = jest.fn(() => ({ valid: [], repairable: [], dead: [] }));
+        const scanSkills = jest.fn(() => ({ valid: [], repairable: [], dead: [], usurped: [] }));
         const { gatherProviderChecks } = require('../../../src/core/diagnostics/provider-checks');
         const facts = gatherProviderChecks(['cursor'], scanSkills);
         const skillsCheck = facts[0].checks.find((c) => c.id === 'skills.global');
@@ -225,7 +225,7 @@ describe('skillsGlobalCheck — renderer-aware (Task 4.4 / deferred Task 4.3 fin
         fs_1.default.rmSync(content, { recursive: true, force: true });
     });
     it('non-link renderer with an empty/missing dir reports absent, not a false healthy', () => {
-        const scanSkills = jest.fn(() => ({ valid: [], repairable: [], dead: [] }));
+        const scanSkills = jest.fn(() => ({ valid: [], repairable: [], dead: [], usurped: [] }));
         const { gatherProviderChecks } = require('../../../src/core/diagnostics/provider-checks');
         const facts = gatherProviderChecks(['cursor'], scanSkills);
         const skillsCheck = facts[0].checks.find((c) => c.id === 'skills.global');
@@ -234,7 +234,7 @@ describe('skillsGlobalCheck — renderer-aware (Task 4.4 / deferred Task 4.3 fin
     it('link renderer (claude-code) behavior is completely unchanged — regression', () => {
         const skillsDir = path_1.default.join(tmpHome, '.claude/skills');
         fs_1.default.mkdirSync(skillsDir, { recursive: true });
-        const scanSkills = jest.fn(() => ({ valid: ['using-awm'], repairable: [], dead: [] }));
+        const scanSkills = jest.fn(() => ({ valid: ['using-awm'], repairable: [], dead: [], usurped: [] }));
         const { gatherProviderChecks } = require('../../../src/core/diagnostics/provider-checks');
         const facts = gatherProviderChecks(['claude-code'], scanSkills);
         const skillsCheck = facts[0].checks.find((c) => c.id === 'skills.global');
@@ -244,7 +244,7 @@ describe('skillsGlobalCheck — renderer-aware (Task 4.4 / deferred Task 4.3 fin
     it('link renderer (claude-code) still reports broken links — regression', () => {
         const skillsDir = path_1.default.join(tmpHome, '.claude/skills');
         fs_1.default.mkdirSync(skillsDir, { recursive: true });
-        const scanSkills = jest.fn(() => ({ valid: [], repairable: ['stale-skill'], dead: [] }));
+        const scanSkills = jest.fn(() => ({ valid: [], repairable: ['stale-skill'], dead: [], usurped: [] }));
         const { gatherProviderChecks } = require('../../../src/core/diagnostics/provider-checks');
         const facts = gatherProviderChecks(['claude-code'], scanSkills);
         const skillsCheck = facts[0].checks.find((c) => c.id === 'skills.global');
@@ -263,7 +263,7 @@ describe('skillsGlobalCheck — renderer-aware (Task 4.4 / deferred Task 4.3 fin
             // neither ends in `.mdc`, so neither is AWM-shaped evidence.
             fs_1.default.writeFileSync(path_1.default.join(rulesDir, 'notes.txt'), 'my own notes, not an AWM rule');
             fs_1.default.mkdirSync(path_1.default.join(rulesDir, 'some-user-dir'));
-            const scanSkills = jest.fn(() => ({ valid: [], repairable: [], dead: [] }));
+            const scanSkills = jest.fn(() => ({ valid: [], repairable: [], dead: [], usurped: [] }));
             const { gatherProviderChecks } = require('../../../src/core/diagnostics/provider-checks');
             const facts = gatherProviderChecks(['cursor'], scanSkills);
             const skillsCheck = facts[0].checks.find((c) => c.id === 'skills.global');
@@ -274,7 +274,7 @@ describe('skillsGlobalCheck — renderer-aware (Task 4.4 / deferred Task 4.3 fin
             fs_1.default.mkdirSync(rulesDir, { recursive: true });
             fs_1.default.writeFileSync(path_1.default.join(rulesDir, 'notes.txt'), 'my own notes, not an AWM rule');
             fs_1.default.writeFileSync(path_1.default.join(rulesDir, 'foo.mdc'), '---\ndescription: foo\nglobs:\nalwaysApply: false\n---\n\nBody.');
-            const scanSkills = jest.fn(() => ({ valid: [], repairable: [], dead: [] }));
+            const scanSkills = jest.fn(() => ({ valid: [], repairable: [], dead: [], usurped: [] }));
             const { gatherProviderChecks } = require('../../../src/core/diagnostics/provider-checks');
             const facts = gatherProviderChecks(['cursor'], scanSkills);
             const skillsCheck = facts[0].checks.find((c) => c.id === 'skills.global');

package/dist/tests/core/init/steps-registry-sync.test.js

@@ -61,7 +61,7 @@ describe('stepCache — registry sync error results', () => {
                 devCore: { present: true, brokenLinks: [] },
                 ambient: { wanted: [], installed: [] },
                 contextInjection: [],
-                globalSkills: { valid: [], repairable: [], dead: [] },
+                globalSkills: { valid: [], repairable: [], dead: [], usurped: [] },
             },
             project: null,
         };

package/dist/tests/core/init/steps.test.js

@@ -23,7 +23,7 @@ function machine() {
         devCore: { present: true, brokenLinks: [] },
         ambient: { wanted: [], installed: [] },
         contextInjection: [],
-        globalSkills: { valid: [], repairable: [], dead: [] },
+        globalSkills: { valid: [], repairable: [], dead: [], usurped: [] },
     };
 }
 function project(over = {}) {
@@ -429,7 +429,7 @@ describe('stepGlobalSkillsRepair', () => {
         const a = spies();
         a.repairGlobalSkills = jest.fn(() => ({ relinked: ['b'], pruned: ['c'], failed: [] }));
         const m = machine();
-        m.globalSkills = { valid: ['a'], repairable: ['b'], dead: ['c'] };
+        m.globalSkills = { valid: ['a'], repairable: ['b'], dead: ['c'], usurped: [] };
         const r = (0, steps_1.stepGlobalSkillsRepair)(deps({ machine: m, project: null }, a));
         expect(r.action).toBe('applied');
         expect(a.repairGlobalSkills).toHaveBeenCalledTimes(1);
@@ -440,7 +440,7 @@ describe('stepGlobalSkillsRepair', () => {
         const a = spies();
         a.repairGlobalSkills = jest.fn(() => ({ relinked: ['b'], pruned: [], failed: [] }));
         const m = machine();
-        m.globalSkills = { valid: [], repairable: ['b'], dead: [] };
+        m.globalSkills = { valid: [], repairable: ['b'], dead: [], usurped: [] };
         const r = (0, steps_1.stepGlobalSkillsRepair)(deps({ machine: m, project: null }, a, { agent: 'opencode' }));
         expect(r.action).toBe('applied');
         expect(a.repairGlobalSkills).toHaveBeenCalledWith((0, providers_1.providerFor)('opencode').skill.global, expect.any(Array));
@@ -451,7 +451,7 @@ describe('stepGlobalSkillsRepair', () => {
         const m = machine();
         // Broken-count is nonzero, so the ONLY thing that can make this skip is the
         // null-global-dir guard itself, not the "nothing broken" early return above.
-        m.globalSkills = { valid: [], repairable: ['b'], dead: ['c'] };
+        m.globalSkills = { valid: [], repairable: ['b'], dead: ['c'], usurped: [] };
         const r = (0, steps_1.stepGlobalSkillsRepair)(deps({ machine: m, project: null }, a, { agent: 'copilot' }));
         expect(r.action).toBe('skipped');
         expect(a.repairGlobalSkills).not.toHaveBeenCalled();

package/dist/tests/core/skill-integrity.test.js

@@ -71,7 +71,7 @@ describe('classifySkillLinks', () => {
     });
     it('returns empty arrays when the skills dir does not exist', () => {
         const result = (0, skill_integrity_1.classifySkillLinks)('/nonexistent/dir', ['/also/nonexistent']);
-        expect(result).toEqual({ valid: [], repairable: [], dead: [] });
+        expect(result).toEqual({ valid: [], repairable: [], dead: [], usurped: [] });
     });
 });
 describe('reconcileAllSkillLinks (#4 — awm update, all providers)', () => {

package/dist/tests/core/usurped-skill-links.test.js

@@ -0,0 +1,126 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+// Un symlink gestionado por AWM que otro instalador reemplaza por un directorio real
+// era INVISIBLE para todo el sistema de diagnostico.
+//
+// Encontrado corriendo el playbook `agent-matrix` para `claude-code` contra el binario
+// publicado: `awm init` dejo `~/.claude/skills/mermaid-diagrams` como symlink al registry
+// baseline y lo anoto en `state/artifacts.json`; la primera sesion real de Claude Code
+// materializo su propia skill `mermaid-diagrams` (bundled, mismo nombre) encima, pisando
+// el symlink con un directorio real distinto — otra `description`, sin `version`, con un
+// README.md que la nuestra no tiene.
+//
+// Despues de eso:
+//   - `awm doctor -a claude-code` reportaba `skills.global: healthy`, `overall: healthy`,
+//     exit 0;
+//   - `awm sync` no lo tocaba;
+//   - el agente cargaba la skill del tercero, no la instalada.
+//
+// La causa es una sola linea de `classifySkillLinks`: `if (!lst.isSymbolicLink()) continue`.
+// Correcta para una skill que el usuario puso a mano — AWM no debe tocarla — y equivocada
+// cuando el ledger de artefactos dice que esa ruta exacta es nuestra. El clasificador nunca
+// consultaba el ledger, asi que no podia distinguir los dos casos.
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const skill_integrity_1 = require("../../src/core/skill-integrity");
+const tmp_1 = require("../support/tmp");
+describe('a managed skill link replaced by third-party content is detected', () => {
+    let registry;
+    let skillsDir;
+    const made = [];
+    const record = (targetPath, renderer = 'link') => ({
+        name: path_1.default.basename(targetPath),
+        type: 'skill',
+        scope: 'global',
+        targetPath,
+        sourcePath: path_1.default.join(registry, 'skills', path_1.default.basename(targetPath)),
+        renderer,
+        owners: ['claude-code'],
+    });
+    beforeEach(() => {
+        registry = (0, tmp_1.mkCanonicalTmpDir)('awm-usurp-reg-');
+        skillsDir = (0, tmp_1.mkCanonicalTmpDir)('awm-usurp-skills-');
+        made.push(registry, skillsDir);
+        fs_1.default.mkdirSync(path_1.default.join(registry, 'skills', 'mermaid-diagrams'), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(registry, 'skills', 'mermaid-diagrams', 'SKILL.md'), '# awm\n');
+    });
+    afterAll(() => { for (const d of made)
+        fs_1.default.rmSync(d, { recursive: true, force: true }); });
+    /** Lo que hace el tercero: borra nuestro symlink y deja su propio directorio. */
+    function usurp(name) {
+        const p = path_1.default.join(skillsDir, name);
+        fs_1.default.rmSync(p, { recursive: true, force: true });
+        fs_1.default.mkdirSync(p, { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(p, 'SKILL.md'), '# someone else\n');
+        return p;
+    }
+    it('reports the replaced entry as usurped, not as healthy', () => {
+        const target = path_1.default.join(skillsDir, 'mermaid-diagrams');
+        fs_1.default.symlinkSync(path_1.default.join(registry, 'skills', 'mermaid-diagrams'), target);
+        // Antes de la usurpacion: un link vivo y nada mas.
+        const managed = (0, skill_integrity_1.managedLinkTargets)([record(target)]);
+        const before = (0, skill_integrity_1.classifySkillLinks)(skillsDir, [registry], managed);
+        expect(before.valid).toEqual(['mermaid-diagrams']);
+        expect(before.usurped).toEqual([]);
+        usurp('mermaid-diagrams');
+        const after = (0, skill_integrity_1.classifySkillLinks)(skillsDir, [registry], managed);
+        expect(after.usurped).toEqual(['mermaid-diagrams']);
+        // Y no se cuela por ninguna de las categorias existentes: `valid` es lo que hace
+        // que `doctor` diga `healthy`, y `repairable`/`dead` mandarian a un remedio
+        // (`repair-global-skills`) que solo toca symlinks y aca no cambiaria nada.
+        expect(after.valid).toEqual([]);
+        expect(after.repairable).toEqual([]);
+        expect(after.dead).toEqual([]);
+    });
+    it('leaves a directory the user created alone — it is not in the ledger', () => {
+        usurp('my-own-skill');
+        const scan = (0, skill_integrity_1.classifySkillLinks)(skillsDir, [registry], (0, skill_integrity_1.managedLinkTargets)([]));
+        expect(scan.usurped).toEqual([]);
+        expect(scan.valid).toEqual([]);
+    });
+    it('does not flag a rendered artifact: a real file is what `cursor-mdc` produces', () => {
+        // El ledger tambien anota artefactos renderizados (`.mdc`, `.instructions.md`).
+        // Para esos, "no es un symlink" es el estado correcto — contarlos como usurpados
+        // pintaria de rojo cada instalacion sana de Cursor y Copilot.
+        const target = path_1.default.join(skillsDir, 'rendered.mdc');
+        fs_1.default.writeFileSync(target, '---\ndescription: x\n---\n');
+        const managed = (0, skill_integrity_1.managedLinkTargets)([record(target, 'cursor-mdc')]);
+        expect(managed.size).toBe(0);
+        expect((0, skill_integrity_1.classifySkillLinks)(skillsDir, [registry], managed).usurped).toEqual([]);
+    });
+    it('defaults to no detection when no ledger is passed (callers without one are unchanged)', () => {
+        usurp('mermaid-diagrams');
+        expect((0, skill_integrity_1.classifySkillLinks)(skillsDir, [registry]).usurped).toEqual([]);
+    });
+});
+// El hallazgo del playbook no fue "el clasificador no ve X" — fue "doctor dice healthy".
+// Detectarlo en `classifySkillLinks` no sirve de nada si el check que lo consume lo
+// descarta, asi que la superficie que reporto el bug se asserta por separado.
+describe('awm doctor degrades on a usurped global skill', () => {
+    const { gatherProviderChecks } = require('../../src/core/diagnostics/provider-checks');
+    function checkFor(usurped, repairable = []) {
+        const scan = jest.fn(() => ({ valid: [], repairable, dead: [], usurped }));
+        const facts = gatherProviderChecks(['claude-code'], scan);
+        return facts[0].checks.find((c) => c.id === 'skills.global');
+    }
+    it('is broken, names what was replaced, and does not offer a remedy that cannot fix it', () => {
+        const check = checkFor(['mermaid-diagrams']);
+        expect(check.state).toBe('broken');
+        expect(check.detail).toContain('mermaid-diagrams');
+        // `repair-global-skills` solo re-linkea symlinks colgantes: mandaria al usuario a
+        // un comando que corre limpio y no cambia nada.
+        expect(check.remediationCode).toBe('reinstall-usurped-skills');
+    });
+    it('still reports plain broken links the old way when nothing was usurped', () => {
+        const check = checkFor([], ['gone']);
+        expect(check.state).toBe('broken');
+        expect(check.detail).toBe('1 broken links');
+        expect(check.remediationCode).toBe('repair-global-skills');
+    });
+    it('is healthy when neither happened', () => {
+        expect(checkFor([]).state).not.toBe('broken');
+    });
+});

package/package.json

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