agentic-workflow-manager 8.2.1 → 8.3.0

package/dist/src/commands/hooks/claude.js

@@ -19,6 +19,43 @@ const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const providers_1 = require("../../providers");
 const shared_1 = require("./shared");
+const provider_1 = require("../../core/context/provider");
+const orchestrators_1 = require("../../core/orchestrators");
+/**
+ * Materializa el payload compuesto (using-awm + orquestadores declarados) en `skillDest`.
+ *
+ * Antes `using-awm.md` era un symlink al SKILL.md crudo del registry: todo lo que
+ * `buildContext` compone (declared orchestrators — Tasks 1-4) nunca llegaba a Claude
+ * Code, el proveedor PRINCIPAL que este framework existe para servir. Se escribe el
+ * archivo en vez de enlazarlo porque el contenido ya no es un archivo del registry sino
+ * un derivado suyo — igual que `materialize()` hace para los demas proveedores
+ * (core/context/materializer.ts), solo que aca el destino es el propio scriptsDir del
+ * hook en vez del awm-context.md generico.
+ *
+ * Usada por `installClaudeHook` Y por `resyncClaudeHookFiles` — con proposito: si solo
+ * una de las dos escribiera el payload materializado, la otra seguiria symlinkeando al
+ * SKILL.md crudo y el siguiente `awm update` reabriria el mismo bypass que esto cierra.
+ *
+ * Escritura atomica via write-then-rename (post-implementation-qa Finding 1, TOCTOU):
+ * el patron previo (`unlinkSync` seguido de `writeFileSync`) dejaba una ventana entre
+ * ambas llamadas donde un symlink recreado en `skillDest` seria seguido por
+ * `writeFileSync` (que no usa `O_EXCL`), escribiendo a traves de el sobre lo que sea
+ * que apunte. Escribir a un temporal unico en el MISMO directorio (para que el rename
+ * quede en el mismo filesystem y sea atomico) y luego `renameSync` al destino evita eso
+ * por completo: el rename reemplaza la entrada de directorio de forma atomica sin
+ * dereferenciar un symlink preexistente en el destino, y sin ventana entre borrar y
+ * escribir — no hace falta unlink previo, el rename ya sobrescribe en un solo paso.
+ */
+function writeMaterializedSkill(skillDest, registryRoot) {
+    const ctx = (0, provider_1.buildContext)({
+        registryRoot,
+        profileExtensions: [],
+        declaredOrchestrators: (0, orchestrators_1.collectAndWarn)(),
+    });
+    const tmpPath = path_1.default.join(path_1.default.dirname(skillDest), `.using-awm.md.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+    fs_1.default.writeFileSync(tmpPath, ctx.markdown, 'utf-8');
+    fs_1.default.renameSync(tmpPath, skillDest);
+}
 function isAwmEntry(entry, scriptsDir, matcher) {
     return (entry?.matcher === matcher &&
         Array.isArray(entry?.hooks) &&
@@ -39,19 +76,10 @@ function installClaudeHook(options) {
     fs_1.default.mkdirSync(config.scriptsDir, { recursive: true });
     (0, shared_1.syncExecutable)(path_1.default.join(sourceHooks, 'session-start'), path_1.default.join(config.scriptsDir, 'session-start'), options.installMethod);
     (0, shared_1.syncExecutable)(path_1.default.join(sourceHooks, 'run-hook.cmd'), path_1.default.join(config.scriptsDir, 'run-hook.cmd'), options.installMethod);
-    // 3. Link the skill (default: symlink so 'awm update' propagates; fall back to copy if symlink is unavailable, e.g. Windows without Developer Mode)
+    // 3. Materializar el payload compuesto (using-awm + orquestadores declarados) — ver
+    //    writeMaterializedSkill arriba para por que esto ya no es un symlink al SKILL.md crudo.
     const skillDest = path_1.default.join(config.scriptsDir, 'using-awm.md');
-    try {
-        fs_1.default.unlinkSync(skillDest);
-    }
-    catch { /* not exists */ }
-    try {
-        fs_1.default.symlinkSync(sourceSkill, skillDest, 'file'); // ver shared.ts: el tipo no se infiere
-    }
-    catch {
-        // best-effort: copy the single skill file; 'awm update' will not auto-propagate
-        fs_1.default.copyFileSync(sourceSkill, skillDest);
-    }
+    writeMaterializedSkill(skillDest, options.registryRoot);
     // 4. Backup settings if it exists
     const backupPath = (0, shared_1.backupManagedFile)(config.settingsPath);
     // 5. Read or initialize settings
@@ -178,29 +206,17 @@ function uninstallClaudeHook(agent) {
 /** Refresh the Claude hook's script/skill files in place (used by resync). Assumes the caller has verified the settings entry is already present. */
 function resyncClaudeHookFiles(config, registryRoot, method) {
     const sourceHooks = path_1.default.join(registryRoot, 'hooks');
-    const sourceSkill = path_1.default.join(registryRoot, 'skills/using-awm/SKILL.md');
     fs_1.default.mkdirSync(config.scriptsDir, { recursive: true });
     (0, shared_1.syncExecutable)(path_1.default.join(sourceHooks, 'session-start'), path_1.default.join(config.scriptsDir, 'session-start'), method);
     (0, shared_1.syncExecutable)(path_1.default.join(sourceHooks, 'run-hook.cmd'), path_1.default.join(config.scriptsDir, 'run-hook.cmd'), method);
+    // Re-materializar el payload compuesto igual que `installClaudeHook` (arriba) — NO
+    // volver a symlinkear al SKILL.md crudo. Antes este era el segundo escritor del mismo
+    // archivo con el symlink-con-fallback-a-copia; si solo `installClaudeHook` se hubiera
+    // arreglado y este no, el primer `awm update` posterior a un install correcto habria
+    // sobreescrito el payload materializado con un symlink crudo de nuevo — reabriendo el
+    // bypass que esto existe para cerrar.
     const skillDest = path_1.default.join(config.scriptsDir, 'using-awm.md');
-    try {
-        fs_1.default.unlinkSync(skillDest);
-    }
-    catch { /* not exists */ }
-    // Mismo fallback a copia que `installClaudeHook` (arriba). Sin el, en
-    // Windows sin Developer Mode este symlink tira EPERM, `resyncInstalledHooks`
-    // propaga el throw y `awm update` devuelve 1 — PARA SIEMPRE: el install
-    // funcionaba (tenia el fallback) y el update no, en una plataforma que la
-    // matriz de soporte declara verificada en CI. Dos escritores del mismo
-    // archivo, solo uno endurecido.
-    try {
-        fs_1.default.symlinkSync(sourceSkill, skillDest, 'file'); // ver shared.ts: el tipo no se infiere
-    }
-    catch {
-        // best-effort: `awm update` no auto-propagara cambios de esta skill,
-        // pero el hook queda funcional en vez de dejar el comando inservible.
-        fs_1.default.copyFileSync(sourceSkill, skillDest);
-    }
+    writeMaterializedSkill(skillDest, registryRoot);
 }
 /** True when the registry has everything needed to resync the Claude hook files. */
 function claudeResyncSourcesExist(registryRoot) {

package/dist/src/commands/hooks/index.js

@@ -58,7 +58,7 @@ function registerHooksCommand(program) {
             console.log(`  Scripts:        ${result.scriptsDir}/session-start`);
             if (agent === 'claude-code') {
                 console.log(`                  ${result.scriptsDir}/run-hook.cmd`);
-                console.log(`                  ${result.scriptsDir}/using-awm.md → ~/.awm/registries/baseline/skills/using-awm/SKILL.md`);
+                console.log(`                  ${result.scriptsDir}/using-awm.md (composed context, written)`);
             }
             console.log('');
             console.log(`  Settings file:  ${result.settingsPath}`);

package/dist/src/commands/hooks/shared.js

@@ -108,7 +108,7 @@ function checkFile(file) {
         return { ok: true, detail: file };
     }
     catch {
-        return { ok: false, detail: `broken link: ${file}` };
+        return { ok: false, detail: `cannot read file: ${file}` };
     }
 }
 /**

package/dist/src/commands/registry/add.js

@@ -12,6 +12,7 @@ const simple_git_1 = __importDefault(require("simple-git"));
 const registries_1 = require("../../core/registries");
 const discovery_1 = require("../../core/discovery");
 const bundles_1 = require("../../core/bundles");
+const orchestrators_1 = require("../../core/orchestrators");
 function deriveRegistryName(remote) {
     // Split on '/', '\' and ':' — not just '/' and ':'. A git remote URL
     // (https://…/repo.git, git@host:org/repo.git) only ever uses the first
@@ -66,6 +67,10 @@ async function addRegistry(remote, nameOverride) {
         fs_1.default.rmSync(dest, { recursive: true, force: true });
         return { ok: false, name, error: e instanceof Error ? e.message : String(e) };
     }
+    // Una declaracion de orquestador malformada se REPORTA, no aborta: el
+    // registry puede aportar skills utiles aunque su declaracion este rota,
+    // y abortar por eso invalidaria contenido sano (R1.2).
+    const { diagnostics: orchestratorDiagnostics } = (0, orchestrators_1.readDeclaredOrchestrators)(dest);
     (0, registries_1.writeRegistriesConfig)([...existing, { name, remote }]);
-    return { ok: true, name, contentRoot: dest };
+    return { ok: true, name, contentRoot: dest, orchestratorDiagnostics };
 }

package/dist/src/commands/registry/index.js

@@ -38,6 +38,9 @@ function registerRegistryCommand(program) {
             process.exit(1);
         }
         s.stop(`Registry ${picocolors_1.default.cyan(result.name)} added at ${result.contentRoot}`);
+        for (const d of result.orchestratorDiagnostics) {
+            console.warn(picocolors_1.default.yellow(`  ⚠  ${d}`));
+        }
         try {
             (0, regenerate_1.regenerateGlobalContext)();
         }

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

@@ -8,6 +8,7 @@ const config_instructions_1 = require("./strategies/config-instructions");
 const codex_agents_1 = require("./strategies/codex-agents");
 const provider_1 = require("./provider");
 const materializer_1 = require("./materializer");
+const orchestrators_1 = require("../orchestrators");
 class InjectionOrchestrator {
     overrides;
     constructor(overrides = {}) {
@@ -41,7 +42,11 @@ class InjectionOrchestrator {
     }
     /** Full input: builds context from registry and materializes to disk. Used by installContext only. */
     inputFor(op) {
-        const ctx = (0, provider_1.buildContext)({ registryRoot: op.registryRoot, profileExtensions: op.profileExtensions });
+        const ctx = (0, provider_1.buildContext)({
+            registryRoot: op.registryRoot,
+            profileExtensions: op.profileExtensions,
+            declaredOrchestrators: (0, orchestrators_1.collectAndWarn)(),
+        });
         const absPath = this.contextPathFor(op);
         const ref = (0, materializer_1.materialize)(ctx, absPath, op.scope);
         return {
@@ -66,7 +71,15 @@ class InjectionOrchestrator {
         const absPath = this.contextPathFor(op);
         let contentHash = '';
         try {
-            const ctx = (0, provider_1.buildContext)({ registryRoot: op.registryRoot, profileExtensions: op.profileExtensions });
+            // Debe recolectar declarados igual que inputFor: si no, el hash "esperado" aqui
+            // diverge del hash realmente materializado por installContext en cuanto algun
+            // registry instalado declare un orquestador, y contextStatus reportaria 'stale'
+            // de forma permanente incluso justo despues de un install correcto.
+            const ctx = (0, provider_1.buildContext)({
+                registryRoot: op.registryRoot,
+                profileExtensions: op.profileExtensions,
+                declaredOrchestrators: (0, orchestrators_1.collectAndWarn)(),
+            });
             contentHash = ctx.contentHash;
         }
         catch (err) {

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

@@ -16,6 +16,33 @@ function parseVersion(skill) {
     const m = skill.match(/^version:\s*["']?([^"'\n]+)["']?\s*$/m);
     return m ? m[1].trim() : '0.0.0';
 }
+/**
+ * Neutraliza contenido no confiable proveniente de registries declarados
+ * (name/appliesWhen/terminatesTo) antes de interpolarlo en markdown.
+ * Sin esto, un registry malicioso/comprometido podria inyectar saltos de
+ * linea, marcadores markdown (##, `, *, _) o pseudo-tags XML/HTML (<, >)
+ * para forjar una seccion nueva o un bloque instruccional dentro del
+ * payload de contexto que consume el proveedor de IA — un vector de
+ * prompt-injection. `readDeclaredOrchestrators` solo valida que los
+ * campos sean strings no vacios; el saneo pertenece a esta frontera de
+ * render, no a la validacion de lectura.
+ */
+function sanitizeForMarkdown(s) {
+    return s.replace(/\r?\n/g, ' ').replace(/[`*_#<>]/g, '');
+}
+function renderDeclared(list) {
+    if (list.length === 0)
+        return '';
+    const rows = list
+        .map(o => {
+        const name = sanitizeForMarkdown(o.name);
+        const appliesWhen = sanitizeForMarkdown(o.appliesWhen);
+        const terminatesTo = sanitizeForMarkdown(o.terminatesTo);
+        return `- **${name}** — applies when: ${appliesWhen}. Terminates to: \`${terminatesTo}\`.`;
+    })
+        .join('\n');
+    return `## Declared orchestrators\n\nConsider these before the built-in pair:\n\n${rows}\n\n`;
+}
 function buildContext(input) {
     const skillPath = path_1.default.join(input.registryRoot, 'skills/using-awm/SKILL.md');
     if (!fs_1.default.existsSync(skillPath)) {
@@ -24,6 +51,7 @@ function buildContext(input) {
     const skill = fs_1.default.readFileSync(skillPath, 'utf-8');
     const exts = input.profileExtensions.length ? input.profileExtensions.join(', ') : 'none';
     const header = `<!-- AWM context (generated) -->\n# AWM\n\nActive extensions: ${exts}\n\n`;
-    const markdown = header + skill;
+    const declared = renderDeclared(input.declaredOrchestrators ?? []);
+    const markdown = header + declared + skill;
     return { markdown, sourceVersion: parseVersion(skill), contentHash: sha256(markdown) };
 }

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

@@ -13,11 +13,28 @@ exports.regenerateGlobalContext = regenerateGlobalContext;
 const fs_1 = __importDefault(require("fs"));
 const providers_1 = require("../../providers");
 const registries_1 = require("../registries");
+const orchestrators_1 = require("../orchestrators");
 const orchestrator_1 = require("./orchestrator");
 function regenerateGlobalContext(targets = [...providers_1.AGENT_TARGETS], orch = new orchestrator_1.InjectionOrchestrator()) {
     const skillsRoot = (0, registries_1.capabilityRoot)('skills');
     if (!skillsRoot)
         return [];
+    // Print each declared-orchestrator diagnostic ONCE up front, rather than letting
+    // every agent's contextStatus/installContext call independently re-collect and
+    // re-warn via InjectionOrchestrator.inputFor/statusInputFor (both call
+    // orchestrators.ts's collectAndWarn() internally, unaware of this outer loop). A
+    // single `awm update` touching N agents (e.g. opencode + codex) would otherwise
+    // print the same diagnostic up to 2x per agent (once from statusInputFor, once
+    // from inputFor when stale) — noisy but not incorrect, since no data is lost or
+    // wrong. This only reduces the printing done BY THIS FUNCTION to one line per
+    // diagnostic; inputFor/statusInputFor still call collectAndWarn() internally per
+    // op (they need the declared list to build/hash context), so a per-agent
+    // duplicate can still print alongside this upfront one. Deeper dedup would mean
+    // threading a pre-collected list through ContextOp/InjectionOrchestrator, which
+    // touches shared collection-scope logic other callers (hooks/claude.ts) rely on —
+    // out of proportion for this minor finding.
+    for (const d of (0, orchestrators_1.collectDeclaredOrchestrators)().diagnostics)
+        console.warn(`warning: ${d}`);
     const out = [];
     for (const agent of targets) {
         const inj = (0, providers_1.providerFor)(agent).injection;
@@ -42,6 +59,18 @@ function regenerateGlobalContext(targets = [...providers_1.AGENT_TARGETS], orch
             if (inj.globalPath === null)
                 continue;
         }
+        else if (inj.type === 'cc-settings-merge') {
+            // Claude Code no pasa por este dispatcher generico: su contexto se
+            // materializa via el hook dedicado (hooks/claude.ts's installClaudeHook/
+            // resyncClaudeHookFiles), invocado por `awm update` a traves de un path
+            // separado (hooks/resync.ts's resyncInstalledHooks). Mismo salteo que
+            // stepContextInjection (init/steps.ts) y contextGlobalCheck
+            // (diagnostics/provider-checks.ts) — "covered by hook". Sin este
+            // continue, orch.contextStatus/installContext corrian igual para
+            // claude-code y escribian un ~/.awm/context/awm-context.md huerfano que
+            // nadie lee (el archivo real vive en el scriptsDir del hook).
+            continue;
+        }
         const op = {
             agent,
             scope: 'global',

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/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');