fix(agents): accept qualified package prose

docs/development/agent-workflow.md

@@ -61,6 +61,8 @@ are recognized as package/alias mentions. Traversal and document-file imports ar
 rejected before those exemptions. TypeScript configuration is parsed as JSONC.
 Declared packages also permit safe subpaths; exact aliases stay exact.
 Declared package mentions may include a version or dist-tag qualifier.
+Qualifier handling includes unscoped names; terminal sentence punctuation is
+removed before matching a declared package.
 Markdown destinations decode HTML entities before URI parsing, matching rendered links.
 Heading-anchor lookup is limited to Markdown targets. Source-file line fragments,
 PDF page fragments and other non-Markdown fragments retain file-existence checks.

tools/skills/validate-agent-guidance.mjs

@@ -114,9 +114,9 @@ async function packageMentions(rootDir) {
         .map((name) => name.slice(1));
     const scopes = new Set(declared.map((name) => name.split('/')[0]));
     return (raw) => {
-        let token = raw.replace(/[.,;:)"'\]}]+$/u, '');
+        let token = raw.replace(/[?!.,;:)"'\]}]+$/u, '');
         token = token.replace(
-            /^([^/]+\/[^/@]+)@(?:[~^]?\d[\w.+-]*|[a-z][\w-]*)$/iu,
+            /^([^/@]+(?:\/[^/@]+)?)@(?:[~^]?\d[\w.+-]*|[a-z][\w-]*)$/iu,
             '$1'
         );
         if (
@@ -124,6 +124,7 @@ async function packageMentions(rootDir) {
         )
             return false;
         if (/\.(?:md|mdx|txt|json|ya?ml|html?)$/iu.test(token)) return false;
+        if (packages.includes(token)) return true;
         if (token.endsWith('/*') && scopes.has(token.slice(0, -2))) return true;
         return declared.some((name) => {
             const star = name.indexOf('*');

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

@@ -847,3 +847,22 @@ for (const [path, fragment] of [
         );
     });
 }
+
+for (const mention of [
+    '@marked@17.0.0',
+    '@marked@^17.0.0',
+    '@angular/core?',
+    '@angular/core!',
+]) {
+    test(`package mention accepts qualifier or punctuation: ${mention}`, async (t) => {
+        assert.deepEqual(
+            await diagnostics(t, {
+                'package.json': JSON.stringify({
+                    dependencies: { marked: '*', '@angular/core': '*' },
+                }),
+                'AGENTS.md': 'Use ' + mention,
+            }),
+            []
+        );
+    });
+}