fix(agents): unify Markdown suffix and encoded import guards

docs/development/agent-workflow.md

@@ -69,7 +69,8 @@ checking the full filename before prefixes at ASCII/Unicode prose separators.
 Declared scoped dependencies, scope wildcards and matching TypeScript path aliases
 are recognized as package/alias mentions. Traversal and document-file imports are
 rejected before those exemptions, including document paths with fragments or queries.
-TypeScript configuration is parsed as JSONC.
+All recognized Markdown extensions share the document-import guard. URL-encoded
+paths do not receive package exemptions. TypeScript configuration is parsed as JSONC.
 Declared packages also permit safe subpaths; exact aliases stay exact.
 Declared package mentions may include a version (including semver comparators) or dist-tag qualifier.
 Qualifier handling includes unscoped names; terminal sentence punctuation is

tools/skills/validate-agent-guidance.mjs

@@ -16,6 +16,8 @@ import {
     guidanceReferences as references,
 } from './agent-guidance-markdown.mjs';
 
+const MARKDOWN_EXTENSION = /\.(?:md|markdown|mdown|mkd|mdx)$/iu;
+
 const SURFACES = [
     'AGENTS.md',
     'CLAUDE.md',
@@ -62,9 +64,7 @@ async function validateReference(
         if (
             anchor &&
             !image &&
-            /^(?:\.md|\.markdown|\.mdown|\.mkd|\.mdx)$/iu.test(
-                extname(actual)
-            ) &&
+            MARKDOWN_EXTENSION.test(extname(actual)) &&
             !anchors(await readFile(actual, 'utf8')).has(anchor)
         ) {
             return `${source}: missing anchor "${anchor}" in ${target}`;
@@ -126,10 +126,11 @@ async function packageMentions(rootDir) {
             token.split(/[\/\\]/u).some((part) => part === '.' || part === '..')
         )
             return false;
+        const path = token.split(/[?#]/u, 1)[0];
         if (
-            /\.(?:md|mdx|txt|json|ya?ml|html?)$/iu.test(
-                token.split(/[?#]/u, 1)[0]
-            )
+            /%[\da-f]{2}/iu.test(token) ||
+            MARKDOWN_EXTENSION.test(path) ||
+            /\.(?:txt|json|ya?ml|html?)$/iu.test(path)
         )
             return false;
         if (packages.includes(token)) return true;

tools/skills/validate-agent-guidance.test.mjs

@@ -1212,3 +1212,27 @@ for (const suffix of [
         );
     });
 }
+
+for (const suffix of [
+    '.markdown',
+    '.mdown',
+    '.mkd',
+    '.md%23rules',
+    '.md%3Fraw',
+    '%2Emd',
+    '/%2e%2e/extra.md',
+]) {
+    test(`document package exemptions reject alternate and encoded paths: ${suffix}`, async (t) => {
+        assert.ok(
+            (
+                await diagnostics(t, {
+                    'package.json': JSON.stringify({
+                        dependencies: { '@angular/core': '*' },
+                    }),
+                    'CLAUDE.md':
+                        '@AGENTS.md\n\nRead @angular/core/docs/extra' + suffix,
+                })
+            ).some((message) => message.includes('additional or inline'))
+        );
+    });
+}