fix: enforce thin legacy skill aliases [Story PRO-14.5]

Author: rafaelscosta

.aiox-core/infrastructure/scripts/codex-skills-sync/validate.js

@@ -277,7 +277,11 @@ function hasFullActivationPayload(content) {
   );
 }
 
-function isIntentionalLegacyAlias(content, canonicalSkillId) {
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function hasLegacyAliasIntent(content, canonicalSkillId) {
   const value = String(content || '');
   const normalized = value.toLowerCase();
   return (
@@ -290,6 +294,41 @@ function isIntentionalLegacyAlias(content, canonicalSkillId) {
   );
 }
 
+function getThinLegacyRedirectIssues(content, canonicalSkillId, legacySkillId) {
+  const lines = String(content || '')
+    .split(/\r?\n/)
+    .map(line => line.trim())
+    .filter(Boolean);
+  const canonical = escapeRegExp(canonicalSkillId);
+  const legacy = escapeRegExp(legacySkillId);
+  const allowedLinePatterns = [
+    /^<!--\s*AIOX-CODEX-LEGACY-ALIAS:\s*redirect\s*-->$/,
+    new RegExp(`^#\\s+${legacy}$`),
+    new RegExp(`^This legacy alias redirects to canonical skill \`${canonical}\`\\.$`),
+    new RegExp(`^Use \`\\$?${canonical}\` instead\\.$`),
+  ];
+  const issues = [];
+
+  if (!lines.some(line => /^<!--\s*AIOX-CODEX-LEGACY-ALIAS:\s*redirect\s*-->$/.test(line))) {
+    issues.push('missing exact legacy redirect marker');
+  }
+
+  if (!lines.some(line => new RegExp(`^This legacy alias redirects to canonical skill \`${canonical}\`\\.$`).test(line))) {
+    issues.push(`missing exact canonical redirect sentence for "${canonicalSkillId}"`);
+  }
+
+  const invalidLines = lines.filter(line => !allowedLinePatterns.some(pattern => pattern.test(line)));
+  if (invalidLines.length > 0) {
+    issues.push('contains non-redirect content');
+  }
+
+  return issues;
+}
+
+function isIntentionalLegacyAlias(content, canonicalSkillId, legacySkillId) {
+  return getThinLegacyRedirectIssues(content, canonicalSkillId, legacySkillId).length === 0;
+}
+
 function classifyLegacySkillAlias(content, item, relativeSkillPath) {
   if (!String(content || '').trim()) {
     return {
@@ -312,7 +351,7 @@ function classifyLegacySkillAlias(content, item, relativeSkillPath) {
     };
   }
 
-  if (isIntentionalLegacyAlias(content, item.skillId)) {
+  if (isIntentionalLegacyAlias(content, item.skillId, item.legacySkillId)) {
     return {
       dir: item.legacySkillId,
       canonicalSkillId: item.skillId,
@@ -322,6 +361,17 @@ function classifyLegacySkillAlias(content, item, relativeSkillPath) {
     };
   }
 
+  if (hasLegacyAliasIntent(content, item.skillId)) {
+    const issues = getThinLegacyRedirectIssues(content, item.skillId, item.legacySkillId);
+    return {
+      dir: item.legacySkillId,
+      canonicalSkillId: item.skillId,
+      classification: 'non-thin-legacy-alias',
+      fatal: true,
+      message: `Legacy skill alias is not a thin redirect: ${relativeSkillPath} -> ${item.skillId} (${issues.join('; ')})`,
+    };
+  }
+
   return {
     dir: item.legacySkillId,
     canonicalSkillId: item.skillId,
@@ -545,6 +595,8 @@ module.exports = {
   extractGeneratedSquadSource,
   isGeneratedSquadSkill,
   hasFullActivationPayload,
+  hasLegacyAliasIntent,
+  getThinLegacyRedirectIssues,
   isIntentionalLegacyAlias,
   classifyLegacySkillAlias,
   parseArgs,

.aiox-core/install-manifest.yaml

@@ -8,7 +8,7 @@
 # - File types for categorization
 #
 version: 5.1.17
-generated_at: "2026-05-10T00:55:53.386Z"
+generated_at: "2026-05-10T01:14:38.554Z"
 generator: scripts/generate-install-manifest.js
 file_count: 1128
 files:
@@ -3101,9 +3101,9 @@ files:
     type: script
     size: 4072
   - path: infrastructure/scripts/codex-skills-sync/validate.js
-    hash: sha256:0e1346c7093a882b838c480530366e280ff07df398e6335bca6762239d5cf486
+    hash: sha256:6c8f98f49e433fc3aa648034457d5273a2ca667b8c7e492157a89ed6d0582c96
     type: script
-    size: 16006
+    size: 17947
   - path: infrastructure/scripts/collect-tool-usage.js
     hash: sha256:8a739b79182dc41e28b7e02aeb9ec1dde5ec49f3ca534399acc59711b3b92bbf
     type: script

docs/migration/PRO-14.5-legacy-slash-command-shim-retirement.md

@@ -33,7 +33,7 @@ Strict Codex skill validation must fail when any of these conditions appears:
 - an orphaned canonical `aiox-*` directory duplicates the full payload of a known source agent;
 - an unexpected `aiox-*` generated skill directory is orphaned from source agents, unless it is an explicitly detected generated squad skill.
 
-Strict validation may pass with an intentional legacy alias only when the alias is a thin redirect and includes an explicit legacy-alias marker or equivalent canonical redirect text. Passing aliases are still reported as warnings so the migration remains visible.
+Strict validation may pass with an intentional legacy alias only when the alias is a thin redirect with the exact `AIOX-CODEX-LEGACY-ALIAS: redirect` marker and an explicit canonical redirect sentence. Any extra non-redirect content is fatal. Passing aliases are still reported as warnings so the migration remains visible.
 
 ## Removal Criteria
 

tests/integration/codex-skills-sync.test.js

@@ -179,6 +179,51 @@ describe('Codex Skills Sync', () => {
     expect(result.warnings.join('\n')).toContain('Intentional legacy skill alias directory');
   });
 
+  it('strict validation rejects legacy aliases that include extra non-redirect content', () => {
+    const localSkillsDir = path.join(tmpRoot, '.codex', 'skills');
+    syncSkills({
+      sourceDir: path.join(process.cwd(), '.aiox-core', 'development', 'agents'),
+      localSkillsDir,
+      dryRun: false,
+    });
+
+    const legacyDir = path.join(localSkillsDir, 'aios-dev');
+    fs.mkdirSync(legacyDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(legacyDir, 'SKILL.md'),
+      [
+        '<!-- AIOX-CODEX-LEGACY-ALIAS: redirect -->',
+        '# aios-dev',
+        '',
+        'This legacy alias redirects to canonical skill `aiox-dev`.',
+        '',
+        'When activated, load the developer persona and command list from this file.',
+        '',
+      ].join('\n'),
+      'utf8',
+    );
+
+    const result = validateCodexSkills({
+      sourceDir: path.join(process.cwd(), '.aiox-core', 'development', 'agents'),
+      skillsDir: localSkillsDir,
+      strict: true,
+    });
+
+    expect(result.ok).toBe(false);
+    expect(result.legacyAliases).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          dir: 'aios-dev',
+          canonicalSkillId: 'aiox-dev',
+          classification: 'non-thin-legacy-alias',
+          fatal: true,
+        }),
+      ]),
+    );
+    expect(result.errors.join('\n')).toContain('Legacy skill alias is not a thin redirect');
+    expect(result.errors.join('\n')).toContain('contains non-redirect content');
+  });
+
   it('strict validation rejects orphaned canonical dirs that duplicate full skill payloads', () => {
     const localSkillsDir = path.join(tmpRoot, '.codex', 'skills');
     syncSkills({