agentic-workflow-manager 4.0.1 → 4.1.1

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

@@ -477,18 +477,43 @@ program.command('list [package]')
     console.log(picocolors_1.default.dim(`  awm list <pkg>  ·  awm list --all`));
     (0, prompts_1.outro)(`Run ${picocolors_1.default.green('awm add')} to install artifacts.`);
 });
-program.command('remove')
-    .description('Remove an installed skill or workflow')
+// Simetrico con `add`: si se puede instalar scripteado, se tiene que poder desinstalar
+// scripteado. `remove` era interactivo puro — sin nombre posicional, sin `--scope`, sin
+// `--yes` — asi que cualquier limpieza automatizada quedaba bloqueada, y el playbook de
+// aceptacion (CORE-17) scripteaba `awm remove dev --yes`, una invocacion que nunca
+// existio. Tercera vez en esta sesion que un playbook se escribio contra lo que la doc
+// prometia y no contra el comportamiento. Ver docs/decisions.md, D-006.
+//
+// El nombre es de BUNDLE, igual que en `add` (D-001).
+program.command('remove [name]')
+    .description('Remove an installed bundle interactively, or non-interactively with flags')
     .option('-a, --agent <agent>', `Target agent(s), comma-separated: ${providers_1.AGENT_TARGETS.join(', ')} (defaults to every enabled agent)`)
-    .action(async (options) => {
+    .option('-s, --scope <scope>', 'Scope: local or global (skips the prompt)')
+    .option('-y, --yes', 'Skip the confirmation prompt (requires a name)')
+    .action(async (name, options) => {
     (0, prompts_1.intro)(picocolors_1.default.bgCyan(picocolors_1.default.black(' AWM - Remove Artifact ')));
     const prefs = (0, config_1.getPreferences)();
+    // `--yes` sin nombre borraria lo que el usuario nunca eligio: un `rm -rf` silencioso
+    // sobre todo lo instalado. Se rechaza antes de tocar nada.
+    if (options.yes && !name) {
+        console.error(picocolors_1.default.red('--yes requires a bundle name: `awm remove <bundle> --yes`.'));
+        console.error(picocolors_1.default.dim('Without a name, removal stays interactive so you see what you are deleting.'));
+        process.exit(1);
+    }
     // Multi-agent selection (matching the add command flow). --agent skips
     // the interactive prompt and resolves the same way as add/sync/update/doctor (R12/R13).
     let targetAgents;
     if (options.agent) {
         targetAgents = resolveTargetsOrExit(prefs, options.agent);
     }
+    else if (options.yes) {
+        // `--yes` significa CERO prompts, no "cero confirmaciones". Sin esto, un
+        // `awm remove dev --yes` sin `--agent` seguia abriendo el multiselect de
+        // agentes y colgaba cualquier script — el flag prometia no-interactivo y no lo
+        // era. Sin `--agent`, el default son los agentes habilitados, igual que en
+        // `add`, `sync`, `update` y `doctor`.
+        targetAgents = [...prefs.enabledAgents];
+    }
     else {
         const agentChoice = await (0, prompts_1.multiselect)({
             message: 'From which agent(s)?',
@@ -502,16 +527,26 @@ program.command('remove')
         handleCancel(agentChoice);
         targetAgents = agentChoice;
     }
-    const scopeChoice = await (0, prompts_1.select)({
-        message: 'Scope?',
-        options: [
-            { value: 'local', label: 'Project (Local)' },
-            { value: 'global', label: 'Global' }
-        ],
-        initialValue: prefs.defaultScope
-    });
-    handleCancel(scopeChoice);
-    const scopeVal = scopeChoice;
+    let scopeVal;
+    if (options.scope) {
+        if (options.scope !== 'local' && options.scope !== 'global') {
+            console.error(picocolors_1.default.red(`Invalid scope "${options.scope}". Use: local or global.`));
+            process.exit(1);
+        }
+        scopeVal = options.scope;
+    }
+    else {
+        const scopeChoice = await (0, prompts_1.select)({
+            message: 'Scope?',
+            options: [
+                { value: 'local', label: 'Project (Local)' },
+                { value: 'global', label: 'Global' }
+            ],
+            initialValue: prefs.defaultScope
+        });
+        handleCancel(scopeChoice);
+        scopeVal = scopeChoice;
+    }
     // projectRoot explicito: `config.local` es relativo, y resolverlo contra
     // `process.cwd()` hacia que `awm remove` no encontrara nada desde un
     // subdirectorio — y que le pasara rutas RELATIVAS a fs.rmSync cuando si.
@@ -532,16 +567,43 @@ program.command('remove')
         }
         return `${icons} ${c.baseName} ${picocolors_1.default.dim(`(in: ${Array.from(locations).join(', ')})`)}`;
     });
-    const toRemove = await (0, prompts_1.multiselect)({
-        message: 'Select artifact(s) to remove',
-        options: groupedOpts,
-        required: true
-    });
-    handleCancel(toRemove);
-    const resolved = resolveSelectedArtifacts(toRemove);
+    let resolved;
+    if (name) {
+        // Los artefactos del bundle pedido que estan REALMENTE instalados en este
+        // scope. Se cruza contra `installed`: lo que no esta instalado no se puede
+        // remover, y decirlo es mejor que borrar un subconjunto en silencio.
+        const bundle = (0, bundles_1.discoverAllBundles)().find((b) => b.name === name);
+        if (!bundle) {
+            console.error(picocolors_1.default.red(`Bundle "${name}" not found in registry.`));
+            console.error(picocolors_1.default.dim('Run `awm list` to see available packages.'));
+            process.exit(1);
+        }
+        const owned = new Set([
+            ...bundle.skills.map((sk) => sk.name),
+            ...bundle.workflows,
+            ...bundle.agents,
+        ]);
+        resolved = installed.filter((a) => owned.has(a.name));
+        if (resolved.length === 0) {
+            (0, prompts_1.outro)(picocolors_1.default.yellow(`Nothing from "${name}" is installed at ${scopeVal} scope for the selected agent(s).`));
+            process.exit(0);
+        }
+    }
+    else {
+        const toRemove = await (0, prompts_1.multiselect)({
+            message: 'Select artifact(s) to remove',
+            options: groupedOpts,
+            required: true
+        });
+        handleCancel(toRemove);
+        resolved = resolveSelectedArtifacts(toRemove);
+    }
     const names = resolved.map(a => picocolors_1.default.red(a.name)).join(', ');
-    const confirmRemove = await (0, prompts_1.confirm)({ message: `Remove ${names}?` });
-    handleCancel(confirmRemove);
+    // `--yes` salta la confirmacion, nunca la seleccion: lo que se borra siempre sale
+    // de un nombre que el usuario escribio.
+    const confirmRemove = options.yes ? true : await (0, prompts_1.confirm)({ message: `Remove ${names}?` });
+    if (!options.yes)
+        handleCancel(confirmRemove);
     if (confirmRemove) {
         try {
             for (const artifact of resolved) {

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