agentic-workflow-manager 8.2.1 → 8.4.0

package/dist/src/core/orchestrators.js

@@ -0,0 +1,142 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readDeclaredOrchestrators = readDeclaredOrchestrators;
+exports.collectDeclaredOrchestrators = collectDeclaredOrchestrators;
+exports.collectAndWarn = collectAndWarn;
+// cli/src/core/orchestrators.ts
+// Lector de declaraciones de orquestador. A diferencia de readRegistryManifest
+// (registries.ts), este parser NUNCA lanza: una declaracion malformada se
+// rechaza y se reporta, sin invalidar el registry que la contiene ni a los
+// demas (R1.2). El contrato admite exactamente cuatro campos — identidad,
+// cuando aplica, y a quien cede el control — y rechaza cualquier otro, que
+// es como se impide que vocabulario de un proceso concreto (o un secreto)
+// entre al framework (R1.3, R5.3).
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const registries_1 = require("./registries");
+const ALLOWED_FIELDS = ['name', 'appliesWhen', 'terminatesTo'];
+// These fields are semantically short (a short identity, a short trigger condition, a
+// short target name) — no legitimate declaration needs more than this. A registry is
+// untrusted input whose fields flow straight into the AI-provider context payload, so an
+// unbounded string here would let a crafted registry bloat/DoS that context.
+const MAX_FIELD_LENGTH = 500;
+function readDeclaredOrchestrators(root) {
+    const file = path_1.default.join(root, registries_1.REGISTRY_MANIFEST_NAME);
+    // Shares the same trust boundary as readRegistryManifest (registries.ts): a manifest
+    // that is a symlink (or otherwise not a regular file) is rejected rather than followed.
+    // assertRegularRegistryFile throws on that case, so it's wrapped locally — this reader
+    // must never throw, only report (R1.2).
+    let exists;
+    try {
+        exists = (0, registries_1.assertRegularRegistryFile)(file);
+    }
+    catch (e) {
+        return { orchestrators: [], diagnostics: [`${file}: ${e instanceof Error ? e.message : String(e)}`] };
+    }
+    if (!exists)
+        return { orchestrators: [], diagnostics: [] };
+    let contents;
+    try {
+        contents = fs_1.default.readFileSync(file, 'utf-8');
+    }
+    catch (e) {
+        return { orchestrators: [], diagnostics: [`${file}: cannot read manifest (${e instanceof Error ? e.message : String(e)})`] };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(contents);
+    }
+    catch (e) {
+        return { orchestrators: [], diagnostics: [`${file}: manifest is not valid JSON (${e instanceof Error ? e.message : String(e)})`] };
+    }
+    const decl = raw?.orchestrator;
+    if (decl === undefined)
+        return { orchestrators: [], diagnostics: [] };
+    if (typeof decl !== 'object' || decl === null || Array.isArray(decl)) {
+        return { orchestrators: [], diagnostics: [`${file}: "orchestrator" must be an object`] };
+    }
+    const problems = [];
+    const entries = decl;
+    for (const key of Object.keys(entries)) {
+        if (!ALLOWED_FIELDS.includes(key)) {
+            // key comes straight from an untrusted registry's JSON — JSON.stringify keeps the
+            // diagnostic single-line and unambiguous even if the key contains newlines or other
+            // control characters, which would otherwise let a crafted key forge extra log lines.
+            problems.push(`unknown field ${JSON.stringify(key)} — the contract admits only ${ALLOWED_FIELDS.join(', ')}`);
+        }
+    }
+    for (const field of ALLOWED_FIELDS) {
+        const value = entries[field];
+        if (typeof value !== 'string' || value.trim() === '') {
+            problems.push(`"${field}" must be a non-empty string`);
+        }
+        else if (value.length > MAX_FIELD_LENGTH) {
+            problems.push(`"${field}" must be at most ${MAX_FIELD_LENGTH} characters`);
+        }
+    }
+    if (problems.length > 0) {
+        return { orchestrators: [], diagnostics: [`${file}: invalid "orchestrator" declaration — ${problems.join('; ')}`] };
+    }
+    return {
+        orchestrators: [{
+                name: entries.name,
+                appliesWhen: entries.appliesWhen,
+                terminatesTo: entries.terminatesTo,
+            }],
+        diagnostics: [],
+    };
+}
+/**
+ * Recolecta declaraciones de orquestador de TODOS los registries instalados (no solo
+ * el que se esta operando) y diagnosticos de las que estan rotas. Nunca lanza:
+ * `readDeclaredOrchestrators` ya garantiza eso por-registry (R1.2), asi que un registry
+ * con declaracion rota se omite del resultado sin impedir construir el contexto (R5.1).
+ *
+ * Vive aca (no en core/context/orchestrator.ts, que la definia originalmente) porque
+ * este modulo es una hoja: solo depende de `./registries`, que a su vez no depende de
+ * nada bajo commands/*. core/context/orchestrator.ts en cambio arrastra
+ * strategies/hook-merge.ts, que importa commands/hooks/install.ts — y claude.ts
+ * necesita esta funcion para cerrar el bypass del SKILL.md crudo (Task 6). Si
+ * `collectAndWarn` siguiera viviendo en orchestrator.ts, que commands/hooks/claude.ts
+ * la importara cerraria un ciclo real: claude.ts -> orchestrator.ts ->
+ * strategies/hook-merge.ts -> commands/hooks/install.ts -> claude.ts.
+ *
+ * Dedupe por "name" entre registries: dos registries instalados pueden declarar el mismo
+ * nombre (posiblemente con appliesWhen/terminatesTo distintos y contradictorios). En vez
+ * de emitir ambas filas al markdown compuesto, gana la primera en el orden de
+ * listRegistries() (= orden de registries.json, ver registries.ts) y la duplicada se
+ * descarta con un diagnostico — misma degradacion tolerante (reportar, no lanzar) que el
+ * resto de este modulo (R1.2, R5.1).
+ */
+function collectDeclaredOrchestrators() {
+    const declared = [];
+    const diagnostics = [];
+    const seenNames = new Set();
+    for (const reg of (0, registries_1.listRegistries)()) {
+        const r = readDeclaredOrchestrators(reg.contentRoot);
+        for (const orch of r.orchestrators) {
+            if (seenNames.has(orch.name)) {
+                const file = path_1.default.join(reg.contentRoot, registries_1.REGISTRY_MANIFEST_NAME);
+                diagnostics.push(`${file}: orchestrator "${orch.name}" duplicates one already declared by an earlier registry — shadowed duplicate dropped`);
+                continue;
+            }
+            seenNames.add(orch.name);
+            declared.push(orch);
+        }
+        diagnostics.push(...r.diagnostics);
+    }
+    return { declared, diagnostics };
+}
+/** Recolecta declarados y emite sus diagnosticos como warnings. Punto unico usado por
+ *  `InjectionOrchestrator.inputFor`/`statusInputFor` y por `commands/hooks/claude.ts`
+ *  para que todos permanezcan sincronizados por construccion (ver R5.1 y el bug de
+ *  staleness que motivo esta extraccion). */
+function collectAndWarn() {
+    const { declared, diagnostics } = collectDeclaredOrchestrators();
+    for (const d of diagnostics)
+        console.warn(`warning: ${d}`);
+    return declared;
+}

package/dist/tests/commands/doctor-is-read-only.test.js

@@ -21,6 +21,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
 describe('awm doctor no escribe nada', () => {
     let home;
     let projectRoot;
@@ -32,7 +33,8 @@ describe('awm doctor no escribe nada', () => {
         process.env.HOME = home;
         process.env.AWM_HOME = path_1.default.join(home, '.awm');
         projectRoot = path_1.default.join(home, 'proj');
-        fs_1.default.mkdirSync(path_1.default.join(projectRoot, '.git'), { recursive: true });
+        fs_1.default.mkdirSync(projectRoot, { recursive: true });
+        (0, child_process_1.execFileSync)('git', ['init', '-q', projectRoot]);
         jest.resetModules();
         writeSpy = jest.spyOn(process.stdout, 'write').mockImplementation(() => true);
     });
@@ -62,6 +64,20 @@ describe('awm doctor no escribe nada', () => {
         walk('.');
         return out.sort();
     };
+    const bytesOf = (dir) => {
+        const out = [];
+        const walk = (sub) => {
+            for (const entry of fs_1.default.readdirSync(path_1.default.join(dir, sub), { withFileTypes: true })) {
+                const rel = path_1.default.join(sub, entry.name);
+                if (entry.isDirectory())
+                    walk(rel);
+                else
+                    out.push([rel, fs_1.default.readFileSync(path_1.default.join(dir, rel)).toString('base64')]);
+            }
+        };
+        walk('.');
+        return out.sort(([left], [right]) => left.localeCompare(right));
+    };
     it('no crea AWM_HOME ni preferences.json en una máquina limpia', () => {
         const { runDoctor } = require('../../src/commands/doctor');
         const before = treeOf(home);
@@ -94,4 +110,41 @@ describe('awm doctor no escribe nada', () => {
         const emitted = writeSpy.mock.calls.map((c) => String(c[0])).join('');
         expect(JSON.parse(emitted).providers.map((p) => p.id)).toEqual(['claude-code']);
     });
+    it('collecting the dashboard leaves project, preferences, journal, ledger, and git bytes unchanged', () => {
+        fs_1.default.mkdirSync(path_1.default.join(home, '.awm', 'ledger'), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(home, '.awm', 'preferences.json'), '{"defaultAgent":"claude-code","enabledAgents":["claude-code"],"installMethod":"symlink","defaultScope":"local"}\n');
+        fs_1.default.writeFileSync(path_1.default.join(home, '.awm', 'ledger', 'events.jsonl'), '{"event":"before"}\n');
+        fs_1.default.mkdirSync(path_1.default.join(projectRoot, '.awm', 'journal'), { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(projectRoot, '.awm', 'profile.json'), '{"extensions":[]}\n');
+        fs_1.default.writeFileSync(path_1.default.join(projectRoot, '.awm', 'journal', 'state.json'), '{"state":"active"}\n');
+        const before = { home: bytesOf(home), project: bytesOf(projectRoot), git: (() => { try {
+                return (0, child_process_1.execFileSync)('git', ['status', '--porcelain=v1'], { cwd: projectRoot, encoding: 'utf8' });
+            }
+            catch (error) {
+                return String(error);
+            } })() };
+        const { collectDashboardSnapshot } = require('../../src/core/dashboard/collect');
+        collectDashboardSnapshot({ cwd: projectRoot, now: '2026-08-22T00:00:00.000Z' });
+        const after = { home: bytesOf(home), project: bytesOf(projectRoot), git: (() => { try {
+                return (0, child_process_1.execFileSync)('git', ['status', '--porcelain=v1'], { cwd: projectRoot, encoding: 'utf8' });
+            }
+            catch (error) {
+                return String(error);
+            } })() };
+        expect(after).toEqual(before);
+    });
+    it('--html replaces only its explicitly requested target', () => {
+        const target = path_1.default.join(projectRoot, 'dashboard.html');
+        fs_1.default.writeFileSync(target, 'old dashboard');
+        const before = { home: bytesOf(home), project: bytesOf(projectRoot) };
+        const { runDoctor } = require('../../src/commands/doctor');
+        const code = runDoctor({ cwd: projectRoot, html: target, force: true });
+        const after = { home: bytesOf(home), project: bytesOf(projectRoot) };
+        expect([0, 1]).toContain(code);
+        const targetFromHome = path_1.default.join('proj', 'dashboard.html');
+        expect(after.home.filter(([name]) => name !== targetFromHome)).toEqual(before.home.filter(([name]) => name !== targetFromHome));
+        expect(after.project.filter(([name]) => name !== 'dashboard.html')).toEqual(before.project.filter(([name]) => name !== 'dashboard.html'));
+        expect(fs_1.default.readFileSync(target, 'utf8')).not.toBe('old dashboard');
+        expect(after.project.map(([name]) => name).filter((name) => name.includes('.tmp'))).toEqual([]);
+    });
 });

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

@@ -4,9 +4,169 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 const doctor_1 = require("../../src/commands/doctor");
+const commander_1 = require("commander");
 const fs_1 = __importDefault(require("fs"));
 const os_1 = __importDefault(require("os"));
 const path_1 = __importDefault(require("path"));
+const dashboard_fixtures_1 = require("../helpers/dashboard-fixtures");
+const types_1 = require("../../src/core/dashboard/types");
+const render_html_1 = require("../../src/core/dashboard/render-html");
+describe('runDoctor legacy JSON fixtures', () => {
+    it.each(['bare-home', 'project'])('keeps %s JSON byte-for-byte compatible', (kind) => {
+        const captured = (0, dashboard_fixtures_1.captureDoctorJsonFixture)(kind);
+        try {
+            const expected = fs_1.default.readFileSync(path_1.default.join(__dirname, '..', 'fixtures', 'doctor-json', `${kind}.json`), 'utf-8');
+            expect(captured.output).toBe(expected);
+            expect(captured.code).toBe(1);
+            const parsed = JSON.parse(captured.output);
+            expect(parsed).toEqual(expect.objectContaining({
+                overall: 'degraded',
+                providers: expect.any(Array),
+            }));
+            const provider = parsed.providers[0];
+            expect(provider).toEqual(expect.objectContaining({
+                id: 'copilot',
+                label: 'Copilot',
+                tier: 'agents-md-managed',
+                checks: expect.any(Array),
+            }));
+            expect(provider.checks).toEqual(expect.arrayContaining([
+                expect.objectContaining({ id: 'context.global', state: kind === 'project' ? 'stale' : 'absent' }),
+            ]));
+        }
+        finally {
+            captured.cleanup();
+        }
+    });
+});
+describe('runDoctor dashboard modes', () => {
+    it('CLI rejects --html without an argument before collection or writes', async () => {
+        const program = new commander_1.Command();
+        const stderr = jest.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        const stdout = jest.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        const previousExitCode = process.exitCode;
+        try {
+            (0, doctor_1.registerDoctorCommand)(program);
+            await program.parseAsync(['node', 'awm', 'doctor', '--html']);
+            expect(process.exitCode).toBe(2);
+            expect(stderr.mock.calls.map((call) => String(call[0])).join('')).toContain('--html requires a file target');
+            expect(stdout).not.toHaveBeenCalled();
+        }
+        finally {
+            process.exitCode = previousExitCode;
+            stderr.mockRestore();
+            stdout.mockRestore();
+        }
+    });
+    it.each([
+        [{ json: true, full: true }, '--json cannot be combined with --full'],
+        [{ json: true, html: 'report.html' }, '--json cannot be combined with --html'],
+        [{ full: true, html: 'report.html' }, '--full cannot be combined with --html'],
+        [{ force: true }, '--force requires --html'],
+        [{ html: '' }, '--html requires a file target'],
+    ])('rejects incompatible options before collection', (options, message) => {
+        const stderr = jest.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        try {
+            expect((0, doctor_1.runDoctor)({ ...options, collectSnapshot: () => { throw new Error('collection must not run'); } })).toBe(2);
+            expect(stderr.mock.calls.map((call) => String(call[0])).join('')).toContain(message);
+        }
+        finally {
+            stderr.mockRestore();
+        }
+    });
+    it('writes exact dashboard bytes and only prints the final path after successful --html', () => {
+        const root = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-doctor-html-success-'));
+        const target = path_1.default.join(root, 'dashboard.html');
+        const stdout = jest.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        const snapshot = (0, types_1.dashboardSnapshot)();
+        try {
+            expect((0, doctor_1.runDoctor)({ cwd: root, html: target, collectSnapshot: () => snapshot })).toBe(0);
+            expect(fs_1.default.readFileSync(target, 'utf8')).toBe((0, render_html_1.renderDashboardHtml)(snapshot));
+            expect(stdout.mock.calls.map((call) => String(call[0]))).toEqual([`${target}\n`]);
+        }
+        finally {
+            stdout.mockRestore();
+            fs_1.default.rmSync(root, { recursive: true, force: true });
+        }
+    });
+    it('maps healthy full, invalid, and failing HTML modes to 0, 2, and 2', () => {
+        const stdout = jest.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        const stderr = jest.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        try {
+            expect((0, doctor_1.runDoctor)({ full: true, cwd: '/definitely-not-a-project', collectSnapshot: () => (0, types_1.dashboardSnapshot)() })).toBe(0);
+            expect((0, doctor_1.runDoctor)({ html: '' })).toBe(2);
+            expect((0, doctor_1.runDoctor)({ html: '/definitely-missing-parent/report.html' })).toBe(2);
+        }
+        finally {
+            stdout.mockRestore();
+            stderr.mockRestore();
+        }
+    });
+    it.each([{ full: true }, { html: 'report.html', force: true }])('returns 1 for a degraded dashboard mode', (options) => {
+        const root = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-doctor-degraded-'));
+        const stdout = jest.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        try {
+            expect((0, doctor_1.runDoctor)({ ...options, cwd: root, collectSnapshot: () => (0, types_1.dashboardSnapshot)({ overall: 'degraded' }) })).toBe(1);
+        }
+        finally {
+            stdout.mockRestore();
+            fs_1.default.rmSync(root, { recursive: true, force: true });
+        }
+    });
+    it('renders a real read-only machine finding and its remediation in full mode', () => {
+        const home = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-doctor-real-dashboard-'));
+        const previousHome = process.env.HOME;
+        const previousAwmHome = process.env.AWM_HOME;
+        const stdout = jest.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        try {
+            process.env.HOME = home;
+            process.env.AWM_HOME = path_1.default.join(home, '.awm');
+            expect((0, doctor_1.runDoctor)({ full: true, cwd: home })).toBe(1);
+            const output = stdout.mock.calls.map((call) => String(call[0])).join('');
+            expect(output).toContain('machine.preferences.missing');
+            expect(output).toContain('awm init');
+            expect(fs_1.default.existsSync(path_1.default.join(home, '.awm', 'preferences.json'))).toBe(false);
+        }
+        finally {
+            stdout.mockRestore();
+            fs_1.default.rmSync(home, { recursive: true, force: true });
+            if (previousHome === undefined)
+                delete process.env.HOME;
+            else
+                process.env.HOME = previousHome;
+            if (previousAwmHome === undefined)
+                delete process.env.AWM_HOME;
+            else
+                process.env.AWM_HOME = previousAwmHome;
+        }
+    });
+    it('wires existing read-only project facts into the dashboard without inventing lifecycle observations', () => {
+        const root = fs_1.default.mkdtempSync(path_1.default.join(os_1.default.tmpdir(), 'awm-doctor-project-facts-'));
+        const stdout = jest.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        try {
+            fs_1.default.writeFileSync(path_1.default.join(root, 'package.json'), '{}');
+            expect((0, doctor_1.runDoctor)({ full: true, cwd: root })).toBe(1);
+            const output = stdout.mock.calls.map((call) => String(call[0])).join('');
+            expect(output).toContain('project.profile.missing');
+            expect(output).toContain('project.sensors.unavailable');
+            expect(output).toContain('unavailable');
+        }
+        finally {
+            stdout.mockRestore();
+            fs_1.default.rmSync(root, { recursive: true, force: true });
+        }
+    });
+    it('applies doctor agent selection validation to full dashboard mode', () => {
+        const stderr = jest.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        try {
+            expect((0, doctor_1.runDoctor)({ full: true, cwd: '/definitely-not-a-project', agent: 'not-a-real-agent' })).toBe(2);
+            expect(stderr.mock.calls.map((call) => String(call[0])).join('')).toContain('Invalid agent');
+        }
+        finally {
+            stderr.mockRestore();
+        }
+    });
+});
 function report(partial = {}) {
     return {
         results: [

package/dist/tests/commands/hooks/install-symlink-fallback.test.js

@@ -6,7 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
-describe('hooks/install — skill symlink fallback to copy', () => {
+describe('hooks/install — symlink fallback to copy', () => {
     let tmpHome;
     let origHome;
     let origAwmHome;
@@ -40,10 +40,18 @@ describe('hooks/install — skill symlink fallback to copy', () => {
         fs_1.default.writeFileSync(path_1.default.join(hooksDir, 'run-hook.cmd'), '#!/bin/sh\n');
         fs_1.default.writeFileSync(path_1.default.join(skillDir, 'SKILL.md'), '# using-awm\n');
     }
-    it('copies the skill when symlink throws (EPERM), preserving content', () => {
+    // Historical note: using-awm.md used to be installed via fs.symlinkSync with an
+    // EPERM fallback to a plain copy — this test used to exercise that fallback.
+    // Task 6 (writeMaterializedSkill, hooks/claude.ts) replaced the symlink entirely
+    // with a materialized write (buildContext() composed markdown via fs.writeFileSync,
+    // after an unlinkSync of any prior file): the skill file never routes through
+    // fs.symlinkSync at all anymore, for any installMethod. The EPERM mock is kept
+    // here specifically to prove that irrelevance — the assertions hold even with
+    // symlinkSync forced to throw, and the explicit "never called" check documents
+    // why: there's no fallback logic left to exercise for this file.
+    it('materializes the skill file — never attempts a symlink, so EPERM on symlinkSync never affects it', () => {
         const registryRoot = path_1.default.join(tmpHome, 'registry');
         seedRegistry(registryRoot);
-        // Force symlinkSync to fail like a platform without symlink permission.
         symlinkSpy = jest.spyOn(fs_1.default, 'symlinkSync').mockImplementation(() => {
             const err = new Error('EPERM: operation not permitted, symlink');
             err.code = 'EPERM';
@@ -53,8 +61,9 @@ describe('hooks/install — skill symlink fallback to copy', () => {
         const result = installHook({ agent: 'claude-code', registryRoot, installMethod: 'copy' });
         const skillDest = path_1.default.join(result.scriptsDir, 'using-awm.md');
         expect(fs_1.default.existsSync(skillDest)).toBe(true);
-        expect(fs_1.default.lstatSync(skillDest).isSymbolicLink()).toBe(false); // it was copied, not linked
+        expect(fs_1.default.lstatSync(skillDest).isSymbolicLink()).toBe(false); // materialized, not linked
         expect(fs_1.default.readFileSync(skillDest, 'utf-8')).toContain('using-awm');
+        expect(symlinkSpy).not.toHaveBeenCalled(); // proves the EPERM mock above was moot
     });
     // Regression: syncExecutable (shared.ts) — used for the hook SCRIPT files
     // (session-start, run-hook.cmd), not just the bootstrap skill above — called

package/dist/tests/commands/hooks/install.test.js

@@ -51,7 +51,10 @@ describe('installHook (happy path + merge)', () => {
         const scriptsDir = path_1.default.join(tmpHome, '.awm/hooks');
         expect(fs_1.default.existsSync(path_1.default.join(scriptsDir, 'session-start'))).toBe(true);
         expect(fs_1.default.existsSync(path_1.default.join(scriptsDir, 'run-hook.cmd'))).toBe(true);
-        expect(fs_1.default.lstatSync(path_1.default.join(scriptsDir, 'using-awm.md')).isSymbolicLink()).toBe(true);
+        // Task 6: using-awm.md is now a materialized file (buildContext's output), not a
+        // symlink to the raw SKILL.md — so declared orchestrators actually reach Claude Code.
+        expect(fs_1.default.lstatSync(path_1.default.join(scriptsDir, 'using-awm.md')).isSymbolicLink()).toBe(false);
+        expect(fs_1.default.readFileSync(path_1.default.join(scriptsDir, 'using-awm.md'), 'utf-8')).toContain('MUST invoke skills.');
         const settings = JSON.parse(fs_1.default.readFileSync(path_1.default.join(tmpHome, '.claude/settings.json'), 'utf-8'));
         expect(settings.hooks.SessionStart).toHaveLength(1);
         expect(settings.hooks.SessionStart[0].matcher).toBe('startup|clear|compact');
@@ -135,11 +138,126 @@ describe('installHook (happy path + merge)', () => {
         // Did not create settings.json
         expect(fs_1.default.existsSync(path_1.default.join(tmpHome, '.claude/settings.json'))).toBe(false);
     });
-    it('symlinks using-awm.md even when installMethod is copy (UX choice)', () => {
+    // Task 6: using-awm.md is materialized (buildContext's composed output), never a
+    // symlink, regardless of installMethod — superseding the pre-Task-6 "UX choice" of
+    // always symlinking this one file even under installMethod 'copy'.
+    it('materializes using-awm.md (never a symlink) even when installMethod is copy', () => {
         const { installHook } = require('../../../src/commands/hooks/install');
         installHook({ agent: 'claude-code', registryRoot: tmpRegistry, installMethod: 'copy' });
         const skillPath = path_1.default.join(tmpHome, '.awm/hooks/using-awm.md');
-        expect(fs_1.default.lstatSync(skillPath).isSymbolicLink()).toBe(true);
+        expect(fs_1.default.lstatSync(skillPath).isSymbolicLink()).toBe(false);
+        expect(fs_1.default.readFileSync(skillPath, 'utf-8')).toContain('MUST invoke skills.');
+    });
+    // Non-regression net (Task 5, Step 1): fixes the hook's observable
+    // contract before Task 6 replaces the symlink with a materialized
+    // file write in claude.ts. Verifies R6.1.
+    it('el hook queda apuntando a un archivo legible con el contenido de using-awm', () => {
+        const { installHook } = require('../../../src/commands/hooks/install');
+        installHook({ agent: 'claude-code', registryRoot: tmpRegistry, installMethod: 'symlink' });
+        const skillDest = path_1.default.join(tmpHome, '.awm/hooks/using-awm.md');
+        expect(fs_1.default.existsSync(skillDest)).toBe(true);
+        const content = fs_1.default.readFileSync(skillDest, 'utf-8');
+        expect(content).toContain('MUST invoke skills.');
+    });
+    // Task 6, Step 1: closes the bypass — everything buildContext composes (declared
+    // orchestrators, Tasks 1-4) must actually reach Claude Code's using-awm.md, not just
+    // the raw SKILL.md. Verifies R1.1.
+    //
+    // Investigation note: the plan's literal sample writes `awm-registry.json` straight
+    // into `tmpRegistry` and expects `collectAndWarn()` to pick it up via `listRegistries()`
+    // — but `listRegistries()` reads registries.json under AWM_HOME, and `tmpRegistry` here
+    // is a bare mkdtemp dir, never registered there via `awm registry add`. Writing the
+    // manifest into an unregistered dir would leave `declared` empty and this test green
+    // for the wrong reason (or red for the wrong reason, pre-fix). Instead this test
+    // registers a REAL listed registry via `writeRegistriesConfig` + `registryContentRoot`
+    // (the same pattern `tests/core/context/orchestrator.test.ts` already uses for this
+    // exact situation) and installs FROM that registry, so `options.registryRoot` and the
+    // one entry `listRegistries()` returns are the same directory — exercising the real
+    // collection path end to end.
+    it('el hook recibe los orquestadores declarados, no el SKILL.md crudo', () => {
+        const { installHook } = require('../../../src/commands/hooks/install');
+        const { writeRegistriesConfig, registryContentRoot } = require('../../../src/core/registries');
+        writeRegistriesConfig([{ name: 'declaring-test', remote: 'unused' }]);
+        const registryRoot = registryContentRoot('declaring-test');
+        const regHooks = path_1.default.join(registryRoot, 'hooks');
+        const regSkill = path_1.default.join(registryRoot, 'skills/using-awm');
+        fs_1.default.mkdirSync(regHooks, { recursive: true });
+        fs_1.default.mkdirSync(regSkill, { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(regHooks, 'session-start'), '#!/usr/bin/env bash\necho "{}"', { mode: 0o755 });
+        fs_1.default.writeFileSync(path_1.default.join(regHooks, 'run-hook.cmd'), '#!/usr/bin/env bash\nexec bash "$1"', { mode: 0o755 });
+        fs_1.default.writeFileSync(path_1.default.join(regSkill, 'SKILL.md'), '---\nname: using-awm\n---\nMUST invoke skills.');
+        fs_1.default.writeFileSync(path_1.default.join(registryRoot, 'awm-registry.json'), JSON.stringify({ orchestrator: { name: 'mi-proceso', appliesWhen: 'al arrancar', terminatesTo: 'development-process' } }));
+        installHook({ agent: 'claude-code', registryRoot, installMethod: 'symlink' });
+        const content = fs_1.default.readFileSync(path_1.default.join(tmpHome, '.awm', 'hooks', 'using-awm.md'), 'utf-8');
+        expect(content).toContain('mi-proceso'); // la composicion LLEGA a Claude Code
+        expect(content).toContain('MUST invoke skills.'); // y el skill sigue entero
+    });
+    // Finding 2 (code quality review, Task 6): regression-locks what the reviewer verified
+    // by hand — a pre-Task-6 install left using-awm.md as a REAL symlink to the registry's
+    // raw SKILL.md. writeMaterializedSkill() must fs.unlinkSync() that symlink (removing
+    // only the directory entry) before writing the materialized file, never dereference it
+    // and clobber the registry's own SKILL.md.
+    it('migrates a pre-Task-6 symlinked using-awm.md to a materialized file without touching the registry SKILL.md', () => {
+        const scriptsDir = path_1.default.join(tmpHome, '.awm/hooks');
+        fs_1.default.mkdirSync(scriptsDir, { recursive: true });
+        const skillDest = path_1.default.join(scriptsDir, 'using-awm.md');
+        const registrySkillPath = path_1.default.join(tmpRegistry, 'skills/using-awm/SKILL.md');
+        const originalSkillContent = fs_1.default.readFileSync(registrySkillPath, 'utf-8');
+        fs_1.default.symlinkSync(registrySkillPath, skillDest, 'file');
+        expect(fs_1.default.lstatSync(skillDest).isSymbolicLink()).toBe(true);
+        const { installHook } = require('../../../src/commands/hooks/install');
+        installHook({ agent: 'claude-code', registryRoot: tmpRegistry, installMethod: 'symlink' });
+        expect(fs_1.default.lstatSync(skillDest).isSymbolicLink()).toBe(false);
+        expect(fs_1.default.readFileSync(skillDest, 'utf-8')).toContain('MUST invoke skills.');
+        // The registry's own SKILL.md must be untouched — proves unlinkSync removed only
+        // the directory entry and never dereferenced/deleted the symlink's target.
+        expect(fs_1.default.existsSync(registrySkillPath)).toBe(true);
+        expect(fs_1.default.readFileSync(registrySkillPath, 'utf-8')).toBe(originalSkillContent);
+    });
+    // Finding 2 (post-implementation-qa, Release 2): R5.1's fail-safe guarantee (a broken
+    // declaration in one registry never blocks context construction for the others) was
+    // already regression-tested for the generic InjectionOrchestrator/opencode path
+    // (tests/core/context/orchestrator.test.ts, 'installContext still succeeds when a
+    // DIFFERENT installed registry has a broken declaration') but not through
+    // installClaudeHook/resyncClaudeHookFiles — Task 6's own highest-risk change. Mirrors
+    // that test's two-registries setup (one valid orchestrator declaration, one broken
+    // JSON) via writeRegistriesConfig/registryContentRoot, same as 'el hook recibe los
+    // orquestadores declarados...' above, but installs from the VALID registry and asserts
+    // the broken sibling never surfaces as a thrown error.
+    it('installHook succeeds and materializes the valid registry\'s orchestrator when a sibling registry has a broken declaration', () => {
+        const { installHook } = require('../../../src/commands/hooks/install');
+        const { writeRegistriesConfig, registryContentRoot } = require('../../../src/core/registries');
+        writeRegistriesConfig([
+            { name: 'broken-sibling', remote: 'unused' },
+            { name: 'valid-declaring', remote: 'unused' },
+        ]);
+        // Broken sibling: unparsable awm-registry.json. No hooks/skill content needed —
+        // it is never the registryRoot passed to installHook, only a sibling
+        // collectAndWarn() walks while gathering declared orchestrators.
+        const brokenRoot = registryContentRoot('broken-sibling');
+        fs_1.default.mkdirSync(brokenRoot, { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(brokenRoot, 'awm-registry.json'), '{ not json');
+        // Valid registry: the one actually installed from.
+        const registryRoot = registryContentRoot('valid-declaring');
+        const regHooks = path_1.default.join(registryRoot, 'hooks');
+        const regSkill = path_1.default.join(registryRoot, 'skills/using-awm');
+        fs_1.default.mkdirSync(regHooks, { recursive: true });
+        fs_1.default.mkdirSync(regSkill, { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(regHooks, 'session-start'), '#!/usr/bin/env bash\necho "{}"', { mode: 0o755 });
+        fs_1.default.writeFileSync(path_1.default.join(regHooks, 'run-hook.cmd'), '#!/usr/bin/env bash\nexec bash "$1"', { mode: 0o755 });
+        fs_1.default.writeFileSync(path_1.default.join(regSkill, 'SKILL.md'), '---\nname: using-awm\n---\nMUST invoke skills.');
+        fs_1.default.writeFileSync(path_1.default.join(registryRoot, 'awm-registry.json'), JSON.stringify({ orchestrator: { name: 'proceso-valido', appliesWhen: 'al arrancar', terminatesTo: 'development-process' } }));
+        const warnSpy = jest.spyOn(console, 'warn').mockImplementation(() => { });
+        let result;
+        expect(() => {
+            result = installHook({ agent: 'claude-code', registryRoot, installMethod: 'symlink' });
+        }).not.toThrow();
+        expect(result.status).toBe('installed');
+        const content = fs_1.default.readFileSync(path_1.default.join(tmpHome, '.awm', 'hooks', 'using-awm.md'), 'utf-8');
+        expect(content).toContain('proceso-valido'); // valid registry's declared orchestrator reached Claude Code
+        expect(content).toContain('MUST invoke skills.'); // and the skill body is intact
+        expect(warnSpy).toHaveBeenCalledWith(expect.stringContaining('warning:')); // broken sibling warned, not thrown
+        warnSpy.mockRestore();
     });
     it('throws for unsupported agent target', () => {
         const { installHook } = require('../../../src/commands/hooks/install');

package/dist/tests/commands/hooks/resync.test.js

@@ -70,7 +70,10 @@ describe('resyncInstalledHooks', () => {
         expect(synced).toContain('NEW VERSION');
         expect(fs_1.default.lstatSync(path_1.default.join(scriptsDir, 'session-start')).isSymbolicLink()).toBe(false);
         expect(() => fs_1.default.accessSync(path_1.default.join(scriptsDir, 'session-start'), fs_1.default.constants.X_OK)).not.toThrow();
-        expect(fs_1.default.lstatSync(path_1.default.join(scriptsDir, 'using-awm.md')).isSymbolicLink()).toBe(true);
+        // Task 6: using-awm.md is materialized (buildContext's output), not a symlink to the
+        // raw SKILL.md — resync must not regress the install path back to a raw symlink.
+        expect(fs_1.default.lstatSync(path_1.default.join(scriptsDir, 'using-awm.md')).isSymbolicLink()).toBe(false);
+        expect(fs_1.default.readFileSync(path_1.default.join(scriptsDir, 'using-awm.md'), 'utf-8')).toContain('MUST invoke skills.');
     });
     it('does NOT touch anything when the hook was never installed (no settings entry)', () => {
         writeRegistry('#!/usr/bin/env bash\necho "NEW VERSION"');
@@ -82,6 +85,39 @@ describe('resyncInstalledHooks', () => {
         ]);
         expect(fs_1.default.existsSync(path_1.default.join(tmpHome, '.awm/hooks/session-start'))).toBe(false);
     });
+    // Task 6, Step 5 regression guard: the exact staleness the plan calls "el hallazgo mas
+    // importante" — if resyncClaudeHookFiles ever regressed back to symlinking the raw
+    // SKILL.md (instead of writing buildContext's materialized output, same as
+    // installClaudeHook), `awm update` would silently strip declared orchestrators back
+    // out of Claude Code's context on the very next resync after a correct install.
+    it('re-materializes using-awm.md with declared orchestrators on resync, not a raw-SKILL.md symlink', () => {
+        const { writeRegistriesConfig, registryContentRoot } = require('../../../src/core/registries');
+        writeRegistriesConfig([{ name: 'declaring-resync-test', remote: 'unused' }]);
+        const registryRoot = registryContentRoot('declaring-resync-test');
+        const regHooks = path_1.default.join(registryRoot, 'hooks');
+        const regSkill = path_1.default.join(registryRoot, 'skills/using-awm');
+        fs_1.default.mkdirSync(regHooks, { recursive: true });
+        fs_1.default.mkdirSync(regSkill, { recursive: true });
+        fs_1.default.writeFileSync(path_1.default.join(regHooks, 'session-start'), '#!/usr/bin/env bash\necho "{}"', { mode: 0o755 });
+        fs_1.default.writeFileSync(path_1.default.join(regHooks, 'run-hook.cmd'), '#!/usr/bin/env bash\nexec bash "$1"', { mode: 0o755 });
+        fs_1.default.writeFileSync(path_1.default.join(regSkill, 'SKILL.md'), '---\nname: using-awm\n---\nMUST invoke skills.');
+        fs_1.default.writeFileSync(path_1.default.join(registryRoot, 'awm-registry.json'), JSON.stringify({ orchestrator: { name: 'mi-proceso', appliesWhen: 'al arrancar', terminatesTo: 'development-process' } }));
+        const { installHook } = require('../../../src/commands/hooks/install');
+        installHook({ agent: 'claude-code', registryRoot, installMethod: 'symlink' });
+        const scriptsDir = path_1.default.join(tmpHome, '.awm/hooks');
+        const skillDest = path_1.default.join(scriptsDir, 'using-awm.md');
+        expect(fs_1.default.readFileSync(skillDest, 'utf-8')).toContain('mi-proceso');
+        const { resyncInstalledHooks } = require('../../../src/commands/hooks/resync');
+        const results = resyncInstalledHooks(registryRoot);
+        expect(results).toEqual([
+            { agent: 'claude-code', action: 'resynced' },
+            { agent: 'codex', action: 'not-installed' },
+        ]);
+        expect(fs_1.default.lstatSync(skillDest).isSymbolicLink()).toBe(false);
+        const content = fs_1.default.readFileSync(skillDest, 'utf-8');
+        expect(content).toContain('mi-proceso');
+        expect(content).toContain('MUST invoke skills.');
+    });
     it('preserves symlink install method', () => {
         writeRegistry('#!/usr/bin/env bash\necho "V2"');
         const scriptsDir = path_1.default.join(tmpHome, '.awm/hooks');
@@ -96,7 +132,9 @@ describe('resyncInstalledHooks', () => {
             { agent: 'codex', action: 'not-installed' },
         ]);
         expect(fs_1.default.lstatSync(path_1.default.join(scriptsDir, 'session-start')).isSymbolicLink()).toBe(true);
-        expect(fs_1.default.lstatSync(path_1.default.join(scriptsDir, 'using-awm.md')).isSymbolicLink()).toBe(true);
+        // Task 6: using-awm.md is materialized regardless of the scripts' install method —
+        // it was never governed by `method` in the first place, before or after this change.
+        expect(fs_1.default.lstatSync(path_1.default.join(scriptsDir, 'using-awm.md')).isSymbolicLink()).toBe(false);
     });
     it('skips with registry-missing when the registry has no hooks dir', () => {
         const scriptsDir = path_1.default.join(tmpHome, '.awm/hooks');