fix(agents): convert base file URLs to native paths

docs/development/agent-workflow.md

@@ -62,6 +62,7 @@ ASCII control/space characters before resolution.
 Iframe/embed sources and object data attributes are document references and retain Markdown-target anchor checks.
 Inline iframe srcdoc documents are traversed too, with their own fragment anchors.
 The first active HTML base href sets reference resolution, including nested srcdoc bases.
+Resolved file URLs use native filesystem conversion, including Windows drive paths.
 Explicit srcset attributes must contain at least one parsed candidate.
 Image and media references require nonempty targets that resolve to files, not directories.
 Image references check file existence without interpreting image fragments as

tools/skills/validate-agent-guidance.mjs

@@ -41,12 +41,14 @@ async function validateReference(
     if (unresolvedReference !== undefined)
         return `${source}: unresolved Markdown reference "${unresolvedReference}"`;
     if (image && !target) return `${source}: empty media target`;
+    let resolvedBasePath;
     if (bases?.length) {
         try {
             let base = pathToFileURL(resolve(rootDir, source));
             for (const href of bases) base = new URL(href, base);
             const url = new URL(target, base);
             if (url.protocol !== 'file:') return;
+            resolvedBasePath = fileURLToPath(url);
             target = url.pathname + url.search + url.hash;
             embeddedAnchors = undefined;
         } catch {
@@ -69,9 +71,14 @@ async function validateReference(
         return !anchor || embeddedAnchors.includes(anchor)
             ? undefined
             : `${source}: missing anchor "${anchor}" in iframe srcdoc`;
-    const absolute = path
-        ? resolve(literal ? rootDir : dirname(resolve(rootDir, source)), path)
-        : resolve(rootDir, source);
+    const absolute =
+        resolvedBasePath ??
+        (path
+            ? resolve(
+                  literal ? rootDir : dirname(resolve(rootDir, source)),
+                  path
+              )
+            : resolve(rootDir, source));
     if (!within(rootDir, absolute))
         return `${source}: referenced path escapes repository root: ${target}`;
     try {

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

@@ -1478,3 +1478,14 @@ test('srcdoc bases retain remote and repository containment rules', async (t) =>
         ).some((message) => message.includes('escapes repository'))
     );
 });
+
+test('local HTML base uses native filesystem paths', async (t) => {
+    assert.deepEqual(
+        await diagnostics(t, {
+            'AGENTS.md':
+                '<base href="docs/"><a href="native%20%23%25.md#heading">Guide</a>',
+            'docs/native #%.md': '# Heading',
+        }),
+        []
+    );
+});