feat: spec-informed prose knowledge extraction

Uses the OpenAPI spec as an entity vocabulary to resolve prose
references. When prose says "do not call POST /payments when using
subscriptions," the extractor resolves both entities against the
spec's endpoint and tag lists, producing a typed conflicts_with
edge between payments and subscriptions skills.

Also captures sections and headings as blocks in document metadata
extraction so plain .md content is visible to downstream extractors.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: salmad3

packages/agent-metadata/src/extractors/document.test.ts

@@ -118,9 +118,13 @@ describe('extractDocumentMetadata', () => {
 
     const doc = makeDoc({ children: [section] });
     const result = extractDocumentMetadata(doc);
-    expect(result.blocks).toHaveLength(1);
-    expect(result.blocks[0]!.codeBlocks).toHaveLength(1);
-    expect(result.blocks[0]!.codeBlocks[0]!.lang).toBe('bash');
+    // The section produces a block (annotated) and its heading produces
+    // another (all headings qualify). The annotated section block carries
+    // the code blocks.
+    const annotatedBlock = result.blocks.find((b) => b.codeBlocks.length > 0);
+    expect(annotatedBlock).toBeDefined();
+    expect(annotatedBlock!.codeBlocks).toHaveLength(1);
+    expect(annotatedBlock!.codeBlocks[0]!.lang).toBe('bash');
   });
 
   it('counts words across all blocks', () => {

packages/agent-metadata/src/extractors/document.ts

@@ -95,30 +95,37 @@ export function extractDocumentMetadata(doc: DocumentNode): DocumentMetadata {
       collectInlineRefs(node.children, doc.filePath, blockId);
     }
 
-    // Extract annotated blocks as discrete metadata units
+    // Extract blocks as discrete metadata units.
+    // Annotated blocks always qualify. Headings and sections qualify
+    // unconditionally so that plain .md content is visible to downstream
+    // extractors (prose knowledge, relationship detection).
     const annotations = 'annotations' in node ? node.annotations : undefined;
-    if (annotations && Object.keys(annotations).length > 0) {
+    const hasAnnotations = annotations && Object.keys(annotations).length > 0;
+    const isSection = node.type === 'section';
+    const isHeading = node.type === 'heading';
+
+    if (hasAnnotations || isSection || isHeading) {
       const textContent = extractBlockText(node);
       const headingText =
-        node.type === 'heading'
+        isHeading
           ? extractInlineText(node.children)
-          : node.type === 'section'
+          : isSection
             ? extractInlineText(node.heading.children)
             : undefined;
       const headingDepth =
-        node.type === 'heading'
+        isHeading
           ? node.depth
-          : node.type === 'section'
+          : isSection
             ? node.heading.depth
             : undefined;
 
       blocks.push({
-        id: annotations.id ?? blockId,
-        type: annotations.type ?? node.type,
+        id: (annotations?.id) ?? blockId,
+        type: (annotations?.type) ?? node.type,
         headingText,
         headingDepth,
         textContent,
-        annotations,
+        annotations: annotations ?? {},
         codeBlocks: collectCodeBlocks(node),
         sourcePath: doc.filePath,
         sourceLocation: node.location