feat: address all P1 engineering gaps

- Inference engine: 41 unit tests covering type/audience/answers
  inference, document annotations, tier assignment, immutability
- MCP server: list_skills and get_related tools expose knowledge
  graph edges to agents at runtime
- Agent skills: interface contracts with endpoint method, path,
  parameters, auth requirements, and deprecation status from
  OpenAPI specs
- Coverage agent: outputs adaptation-report.json compatible with
  nous apply, unifying the two suggestion pipelines
- Rate limiter: applied to all MCP tools, not just search_docs
- Type safety: OpenAPI spec validation replaces as-unknown-as cast
- Apply command: test coverage for heading matching and annotation
  formatting

714 tests passing across 13 packages.

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

Author: salmad3

packages/agent-metadata/src/emitters/agent-skills.ts

@@ -105,6 +105,11 @@ function deriveSkills(
       ? confidences.reduce((a, b) => a + b, 0) / confidences.length
       : 0.5;
 
+    // Collect interface contracts from API-derived blocks
+    const endpoints = agentBlocks
+      .filter((b) => b.endpoint !== undefined)
+      .map((b) => b.endpoint!);
+
     skills.push({
       id: skillId,
       name: doc.title,
@@ -115,6 +120,7 @@ function deriveSkills(
       examples: examples.length > 0 ? examples : undefined,
       confidence: Math.round(avgConfidence * 100) / 100,
       tags: tags.size > 0 ? [...tags] : undefined,
+      endpoints: endpoints.length > 0 ? endpoints : undefined,
     });
   }
 

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

@@ -9,15 +9,15 @@ import type { DocumentNode, NousConfig } from '@nousdev/types';
 import type { ExtractedMetadata, ExtractedRelationship, DocumentMetadata } from '../types.js';
 import { extractDocumentMetadata } from './document.js';
 import { extractRelationships } from './relationships.js';
-import { extractFromOpenApi } from './openapi.js';
+import { extractFromOpenApi, type OpenApiSpec } from './openapi.js';
 import { linkSpecAndProse } from './spec-prose-linker.js';
 import { buildSpecVocabulary, extractProseKnowledge } from './prose-knowledge.js';
 
 export { extractInlineText, extractBlockText, estimateTokens, countWords } from './text.js';
 export { extractDocumentMetadata } from './document.js';
 export { inferAnnotations } from './infer-annotations.js';
 export { extractRelationships } from './relationships.js';
-export { extractFromOpenApi } from './openapi.js';
+export { extractFromOpenApi, type OpenApiSpec } from './openapi.js';
 export { linkSpecAndProse } from './spec-prose-linker.js';
 
 export interface ExtractAllOptions {
@@ -27,6 +27,28 @@ export interface ExtractAllOptions {
   readonly rawTexts?: ReadonlyMap<string, string>;
 }
 
+/**
+ * Runtime guard that validates an unknown record contains the required
+ * OpenAPI spec fields: openapi, info.title, info.version, and paths.
+ * Returns the typed spec on success, undefined on failure.
+ */
+function asOpenApiSpec(value: Record<string, unknown>): OpenApiSpec | undefined {
+  if (!value || typeof value !== 'object') return undefined;
+  if (typeof value.openapi !== 'string') return undefined;
+
+  const info = value.info;
+  if (!info || typeof info !== 'object') return undefined;
+  const infoObj = info as Record<string, unknown>;
+  if (typeof infoObj.title !== 'string') return undefined;
+  if (typeof infoObj.version !== 'string') return undefined;
+
+  if (value.paths !== undefined && (typeof value.paths !== 'object' || value.paths === null)) {
+    return undefined;
+  }
+
+  return value as unknown as OpenApiSpec;
+}
+
 /** Extract metadata from all documents in a build. */
 export function extractAll(
   documents: readonly DocumentNode[],
@@ -41,7 +63,9 @@ export function extractAll(
   const specRelationships: ExtractedRelationship[] = [];
 
   for (const spec of options?.openapiSpecs ?? []) {
-    const extracted = extractFromOpenApi(spec as unknown as Parameters<typeof extractFromOpenApi>[0]);
+    const validated = asOpenApiSpec(spec);
+    if (!validated) continue;
+    const extracted = extractFromOpenApi(validated);
     specDocs.push(...extracted.documents);
     specRelationships.push(...extracted.relationships);
   }

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

@@ -24,7 +24,7 @@ import type {
 } from '../types.js';
 
 
-interface OpenApiSpec {
+export interface OpenApiSpec {
   readonly openapi: string;
   readonly info: {
     readonly title: string;
@@ -360,6 +360,22 @@ function groupOperationsIntoDocuments(
       },
       codeBlocks: [],
       sourcePath: `openapi:${tag}`,
+      endpoint: {
+        method: op.method,
+        path: op.path,
+        summary: op.summary || op.operationId,
+        parameters: op.parameters.map((p) => ({
+          name: p.name,
+          in: p.in,
+          required: p.required ?? false,
+          type: p.schema?.type ?? 'string',
+          description: p.description,
+        })),
+        requestBodySchema: op.referencedSchemas[0],
+        responseSchema: op.referencedSchemas[0],
+        authRequired: op.securitySchemes.length > 0,
+        deprecated: op.deprecated,
+      },
     }));
 
     documents.push({

packages/agent-metadata/src/types.ts

@@ -26,6 +26,8 @@ export interface ExtractedBlock {
     readonly startLine: number;
     readonly endLine: number;
   };
+  /** Interface contract for API-derived blocks. */
+  readonly endpoint?: SkillEndpoint;
 }
 
 /** A code block extracted with its language and raw value. */
@@ -340,6 +342,28 @@ export interface AgentSkill {
   readonly examples?: readonly string[];
   readonly confidence: number;
   readonly tags?: readonly string[];
+  /** Interface contracts for API-derived skills. */
+  readonly endpoints?: readonly SkillEndpoint[];
+}
+
+/** Machine-actionable endpoint definition within a skill. */
+export interface SkillEndpoint {
+  readonly method: string;
+  readonly path: string;
+  readonly summary: string;
+  readonly parameters?: readonly SkillParameter[];
+  readonly requestBodySchema?: string;
+  readonly responseSchema?: string;
+  readonly authRequired: boolean;
+  readonly deprecated: boolean;
+}
+
+export interface SkillParameter {
+  readonly name: string;
+  readonly in: string;
+  readonly required: boolean;
+  readonly type: string;
+  readonly description?: string;
 }
 
 export interface SkillEdge {

packages/agents/src/coverage-agent.ts

@@ -202,13 +202,38 @@ export async function runCoverageAgent(
     suggestions: allSuggestions,
   };
 
-  // Write report
+  // Write coverage report
   const reportPath = join(outDir, 'coverage-report.json');
   await writeFile(reportPath, JSON.stringify(report, null, 2), 'utf-8');
 
+  // Also write in adaptation-report format so `nous apply` can consume it
+  const adaptationSuggestions = allSuggestions.map((s) => ({
+    chunkId: `coverage-${s.filePath}-${s.section}`.replace(/[^a-z0-9-]/gi, '-'),
+    documentPath: s.filePath,
+    section: s.section,
+    suggestionType: 'add_answers' as const,
+    detail: s.reasoning,
+    priority: s.confidence,
+    suggestedAnnotation: `{answers: "${s.suggestedAnswers}"}`,
+  }));
+
+  const adaptationReport = {
+    generatedAt: report.generatedAt,
+    source: 'coverage-agent',
+    suggestions: adaptationSuggestions,
+    metrics: {
+      filesAnalyzed: report.filesAnalyzed,
+      totalSuggestions: report.totalSuggestions,
+    },
+  };
+
+  const adaptationPath = join(outDir, 'adaptation-report.json');
+  await writeFile(adaptationPath, JSON.stringify(adaptationReport, null, 2), 'utf-8');
+
   console.log('');
   console.log(`✓ Coverage Report: ${report.totalSuggestions} suggestions across ${report.filesAnalyzed} files`);
   console.log(`  Saved to ${reportPath}`);
+  console.log(`  Compatible with \`nous apply\`: ${adaptationPath}`);
 
   return report;
 }