fix(agents): exclude opaque URI prose from import scans

docs/development/agent-workflow.md

@@ -71,7 +71,9 @@ HTML video, audio, source and track `src` assets and video posters use the same
 existence checks as images. Entity decoding uses full HTML text/attribute rules,
 including references whose semicolon may be omitted.
 Inline guidance imports are rejected after punctuation as well as whitespace.
-At-signs inside external URLs are excluded per HTML text node, preserving adjacent imports.
+At-signs inside external URIs (including opaque schemes such as mailto) are excluded
+per HTML text node, preserving adjacent imports. A colon directly before an import
+does not make that import a URI.
 A closing bracket followed by punctuation and an at-sign terminates a bare URL exclusion.
 Extensionless inline candidates are also imports when they resolve to repository files,
 checking the full filename before prefixes at ASCII/Unicode prose separators.

tools/skills/agent-guidance-markdown.mjs

@@ -147,7 +147,7 @@ export function guidanceProse(markdown) {
             return ' ';
         if (node.nodeName === '#text')
             return node.value.replace(
-                /(?:\b[a-z][a-z\d+.-]*:\/\/|\/\/)[^\s]*?(?=[)\]}>][.,;:!?]*@|\s|$)/giu,
+                /(?:\b[a-z][a-z\d+.-]*:(?![@\s])|\/\/)[^\s]*?(?=[)\]}>][.,;:!?]*@|\s|$)/giu,
                 ' '
             );
         const content = (node.childNodes ?? []).map(text).join('');

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

@@ -1504,3 +1504,22 @@ for (const boundary of [').', '];', '}']) {
         );
     });
 }
+
+for (const uri of [
+    '<mailto:user@example.com?subject=@docs/guide.md>',
+    'mailto:user@example.com?subject=@docs/guide.md',
+    '<urn:example:@docs/guide.md>',
+]) {
+    test(`opaque URI is not a guidance import: ${uri}`, async (t) => {
+        assert.deepEqual(await diagnostics(t, { 'AGENTS.md': uri }), []);
+    });
+}
+test('colon directly before an import remains checked', async (t) => {
+    assert.ok(
+        (
+            await diagnostics(t, {
+                'CLAUDE.md': '@AGENTS.md\n\nRead:@docs/guide.md',
+            })
+        ).some((message) => message.includes('additional or inline'))
+    );
+});