@warpgogol/werkstatt-shared 0.14.1 → 0.16.0

package/src/{share/agent → agent}/search.ts

@@ -14,7 +14,13 @@ no timestamps in the hash payload.
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0954: initial search manifest contract, query/response types, and pure builder.</item>
-  <item>m000101: add NON_KNOWLEDGE_FILES and isNonKnowledgeFile for shared non-knowledge-file exclusion.</item>
+  <item>RFC-1097: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
+  <item>RFC-1097: sweep — werkstatt-engine clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
+  <item>RFC-1115: SearchChunk gains citation fields (title, canonicalUrl, updatedAt); SearchResult flattened to { title, canonicalUrl, updatedAt, lang, type, score, text }; SEARCH_MANIFEST_SCHEMA_VERSION "1" → "2".</item>
 </CHANGE_SUMMARY>
 */
 
@@ -39,8 +45,8 @@ export const SEARCH_DEFAULT_TOP_K = 5;
 /** Maximum character length for a chunk's `text` field (truncated before embedding). */
 export const SEARCH_CHUNK_TEXT_MAX_LENGTH = 2000;
 
-/** Schema version for the search manifest. */
-export const SEARCH_MANIFEST_SCHEMA_VERSION = "1";
+/** Schema version for the search manifest. RFC-1115: "2" adds citation fields to chunks. */
+export const SEARCH_MANIFEST_SCHEMA_VERSION = "2";
 
 /** Static asset path for the generated search manifest. */
 export const SEARCH_MANIFEST_PATH = "public/api/agent/v1/search-manifest.json";
@@ -81,6 +87,12 @@ export interface SearchChunk {
   heading: string | null;
   /** Body text extracted from the block, truncated to SEARCH_CHUNK_TEXT_MAX_LENGTH. */
   text: string;
+  /** RFC-1115: display title for citations (from heading; null when absent). */
+  title: string | null;
+  /** RFC-1115: absolute canonical URL (site origin + url) — citable without a follow-up fetch. */
+  canonicalUrl: string;
+  /** RFC-1115: source-backed update stamp YYYY-MM-DD (RFC-0317); null when unknown. */
+  updatedAt: string | null;
 }
 
 /** Static search manifest — build-time output written to public/api/agent/v1/search-manifest.json. */
@@ -112,11 +124,25 @@ export interface SearchQuery {
   topK?: number;
 }
 
-/** A single search result — chunk + similarity score. */
+/**
+ * RFC-1115: a single search result — flattened citation shape.
+ * Carries everything an agent needs to cite without a follow-up fetch.
+ */
 export interface SearchResult {
-  chunk: SearchChunk;
+  /** Display title (from chunk heading; null when absent). */
+  title: string | null;
+  /** Absolute canonical URL of the chunk's page or resource. */
+  canonicalUrl: string;
+  /** Source-backed update stamp YYYY-MM-DD (RFC-0317); null when unknown. */
+  updatedAt: string | null;
+  /** ISO 639-1 language code. */
+  lang: string;
+  /** Content type of the underlying chunk. */
+  type: SearchChunkType;
   /** Cosine similarity score (0..1, higher = more similar). */
   score: number;
+  /** Body text of the chunk. */
+  text: string;
 }
 
 /** Response from the search endpoint. */

package/src/{share → agent}/tests/api-catalog.test.ts

@@ -8,15 +8,17 @@
 </MODULE_MAP>
 <CHANGE_SUMMARY>
   <item>RFC-0783: initial API Catalog projection tests.</item>
+  <item>RFC-1113: align agent discovery surface with RFC 9727 and MCP 2026-07-28 stateless era</item>
 </CHANGE_SUMMARY>
 */
 
 import { test, expect } from "vitest";
-import { buildApiCatalog } from "../agent/api-catalog.ts";
-import { buildAgentSurfaceManifest } from "../agent/manifest.ts";
+import { buildApiCatalog } from "../api-catalog.ts";
+import { buildAgentSurfaceManifest } from "../manifest.ts";
 
 test("buildApiCatalog: empty manifest yields service-meta + service-doc links", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -34,6 +36,7 @@ test("buildApiCatalog: empty manifest yields service-meta + service-doc links",
 
 test("buildApiCatalog: one knowledge ref → one item link", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -51,6 +54,7 @@ test("buildApiCatalog: one knowledge ref → one item link", () => {
 
 test("buildApiCatalog: mcp interface adds service-desc + service links", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -69,6 +73,7 @@ test("buildApiCatalog: determinism — same input produces identical output", ()
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
+    generatedAt: "2026-01-01T00:00:00.000Z",
     knowledge: [
       { domain: "offer", url: "/api/agent/v1/offer.json", schema: "gogol.agent.knowledge/offer@1" },
       { domain: "team", url: "/api/agent/v1/team.json", schema: "gogol.agent.knowledge/team@1" },
@@ -82,6 +87,7 @@ test("buildApiCatalog: determinism — same input produces identical output", ()
 
 test("buildApiCatalog: links are sorted by href within each relation", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },

package/src/{share → agent}/tests/ard-catalog.test.ts

@@ -5,15 +5,17 @@
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>Initial ARD ai-catalog.json projection tests.</item>
+  <item>RFC-1113: align agent discovery surface with RFC 9727 and MCP 2026-07-28 stateless era</item>
 </CHANGE_SUMMARY>
 */
 
 import { test, expect } from "vitest";
-import { buildArdCatalog } from "../agent/ard-catalog.ts";
-import { buildAgentSurfaceManifest } from "../agent/manifest.ts";
+import { buildArdCatalog } from "../ard-catalog.ts";
+import { buildAgentSurfaceManifest } from "../manifest.ts";
 
 test("buildArdCatalog: produces specVersion, host, and entries array", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -27,6 +29,7 @@ test("buildArdCatalog: produces specVersion, host, and entries array", () => {
 
 test("buildArdCatalog: each entry has identifier, displayName, type, url, representativeQueries", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -48,6 +51,7 @@ test("buildArdCatalog: each entry has identifier, displayName, type, url, repres
 
 test("buildArdCatalog: MCP interface adds MCP server entry", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -62,6 +66,7 @@ test("buildArdCatalog: MCP interface adds MCP server entry", () => {
 
 test("buildArdCatalog: knowledge refs produce entries", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -78,6 +83,7 @@ test("buildArdCatalog: knowledge refs produce entries", () => {
 
 test("buildArdCatalog: entries are sorted by identifier", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -97,6 +103,7 @@ test("buildArdCatalog: determinism — same input produces identical output", ()
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
+    generatedAt: "2026-01-01T00:00:00.000Z",
     knowledge: [
       { domain: "offer", url: "/api/agent/v1/offer.json", schema: "gogol.agent.knowledge/offer@1" },
     ],
@@ -109,6 +116,7 @@ test("buildArdCatalog: determinism — same input produces identical output", ()
 
 test("buildArdCatalog: host identifier uses did:web format with domain", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "warpgogol-com",
     baseUrl: "https://warpgogol.com",
     languages: { default: "de", supported: ["de"] },
@@ -120,6 +128,7 @@ test("buildArdCatalog: host identifier uses did:web format with domain", () => {
 
 test("buildArdCatalog: default hostDisplayName falls back to site name", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "my-site",
     baseUrl: "https://example.com",
     languages: { default: "de", supported: ["de"] },

package/src/{share → agent}/tests/capability.test.ts

@@ -16,7 +16,7 @@ import {
   resolveActiveCapabilities,
   capabilityToActionRef,
   type CapabilityRecord,
-} from "../agent/capability.ts";
+} from "../capability.ts";
 
 function makeCap(overrides: Partial<CapabilityRecord> = {}): CapabilityRecord {
   return {

package/src/{share → agent}/tests/fleet-catalog.test.ts

@@ -16,7 +16,7 @@ import {
   buildFleetAgentCatalog,
   computeFleetCatalogContentHash,
   FLEET_AGENT_CATALOG_SCHEMA,
-} from "../agent/fleet-catalog.ts";
+} from "../fleet-catalog.ts";
 
 const sampleDoc = {
   surfaceVersion: "1.0.0",

package/src/{share → agent}/tests/knowledge.test.ts

@@ -16,8 +16,8 @@ import {
   AGENT_KNOWLEDGE_DOMAINS,
   isAgentKnowledgeDomain,
   formatAgentKnowledge,
-} from "../agent/knowledge.ts";
-import { BUSINESS_DOMAIN_VISIBILITY } from "../semantic/business-projection.ts";
+} from "../knowledge.ts";
+import { BUSINESS_DOMAIN_VISIBILITY } from "../../semantic/business-projection.ts";
 
 test("AGENT_KNOWLEDGE_DOMAINS: matches exactly the `public` BUSINESS_DOMAIN_VISIBILITY keys", () => {
   const publicDomains = Object.entries(BUSINESS_DOMAIN_VISIBILITY)

package/src/{share → agent}/tests/manifest.test.ts

@@ -9,22 +9,27 @@
 <CHANGE_SUMMARY>
   <item>RFC-0286: initial builder tests.</item>
   <item>RFC-0954: add search interface tests.</item>
+  <item>RFC-1113: align agent discovery surface with RFC 9727 and MCP 2026-07-28 stateless era</item>
+  <item>RFC-1114: add a2a interface + supportedProtocols tests (AC-5).</item>
+  <item>RFC-1114: minimal real A2A endpoint + honest agent card</item>
 </CHANGE_SUMMARY>
 */
 
 import { test, expect } from "vitest";
 import {
+  AGENT_SURFACE_SCHEMA_ID,
   AGENT_SURFACE_VERSION,
   buildAgentSurfaceManifest,
   computeAgentManifestContentHash,
   computeSignedContentHash,
   canonicalJson,
-} from "../agent/manifest.ts";
+} from "../manifest.ts";
 
 const baseInput = {
   site: "warpgogol-com",
   baseUrl: "https://warpgogol.com/",
   languages: { default: "de", supported: ["uk", "de"] },
+  generatedAt: "2026-01-01T00:00:00.000Z",
 };
 
 test("buildAgentSurfaceManifest: strips trailing slash and sorts supported languages", () => {
@@ -39,6 +44,7 @@ test("buildAgentSurfaceManifest: safe default — empty knowledge/actions, null
   expect(m.actions).toEqual([]);
   expect(m.interfaces.openapi).toBe(null);
   expect(m.interfaces.mcp).toBe(null);
+  expect(m.interfaces.a2a).toBe(null);
   expect(m.interfaces.twins).toBe(null);
   expect(m.interfaces.search).toBe(null);
   expect(m.proof).toBe(null);
@@ -149,3 +155,68 @@ test("computeSignedContentHash: matches computeAgentManifestContentHash for same
   const doc = { a: 1, b: 2, contentHash: "x", proof: null };
   expect(computeSignedContentHash(doc)).toBe(computeAgentManifestContentHash(doc));
 });
+
+// ---------------------------------------------------------------------------
+// RFC-1113: discovery metadata fields
+// ---------------------------------------------------------------------------
+
+test("buildAgentSurfaceManifest: emits $schema, generatedAt, supportedProtocols", () => {
+  const m = buildAgentSurfaceManifest(baseInput);
+  expect(m.$schema).toBe(AGENT_SURFACE_SCHEMA_ID);
+  expect(m.generatedAt).toBe("2026-01-01T00:00:00.000Z");
+  // Unconditional discovery artifacts only — no interfaces were provided.
+  expect(m.supportedProtocols).toEqual(["agent-skills", "ard", "dns-aid", "linkset", "llms"]);
+});
+
+test("buildAgentSurfaceManifest: supportedProtocols follows emitted interfaces", () => {
+  const m = buildAgentSurfaceManifest({
+    ...baseInput,
+    hasTwins: true,
+    openapiUrl: "/.well-known/agent.openapi.json",
+    mcp: { url: "/api/agent/mcp", protocolVersion: "2026-07-28" },
+    search: { url: "/api/agent/search", model: "@cf/baai/bge-m3", dimensions: 1024 },
+  });
+  expect(m.supportedProtocols).toEqual([
+    "agent-skills",
+    "ard",
+    "dns-aid",
+    "linkset",
+    "llms",
+    "mcp",
+    "openapi",
+    "search",
+    "twins",
+  ]);
+});
+
+// ---------------------------------------------------------------------------
+// RFC-1114: a2a interface (AC-5)
+// ---------------------------------------------------------------------------
+
+test("buildAgentSurfaceManifest: populates interfaces.a2a and lists a2a in supportedProtocols", () => {
+  const m = buildAgentSurfaceManifest({
+    ...baseInput,
+    a2a: { url: "/api/agent/a2a", protocolVersion: "1.0" },
+  });
+  expect(m.interfaces.a2a).toEqual({ url: "/api/agent/a2a", protocolVersion: "1.0" });
+  expect(m.supportedProtocols).toContain("a2a");
+});
+
+test("buildAgentSurfaceManifest: a2a absent from supportedProtocols when no a2a interface", () => {
+  const m = buildAgentSurfaceManifest(baseInput);
+  expect(m.interfaces.a2a).toBe(null);
+  expect(m.supportedProtocols).not.toContain("a2a");
+});
+
+test("buildAgentSurfaceManifest: generatedAt does not change contentHash (AC-3)", () => {
+  const a = buildAgentSurfaceManifest(baseInput);
+  const b = buildAgentSurfaceManifest({ ...baseInput, generatedAt: "2026-12-31T23:59:59.000Z" });
+  expect(a.contentHash).toBe(b.contentHash);
+  expect(a.generatedAt).not.toBe(b.generatedAt);
+});
+
+test("computeAgentManifestContentHash: excludes generatedAt", () => {
+  const doc = { a: 1, generatedAt: "2026-01-01T00:00:00Z" };
+  const other = { a: 1, generatedAt: "2026-06-06T06:06:06Z" };
+  expect(computeAgentManifestContentHash(doc)).toBe(computeAgentManifestContentHash(other));
+});

package/src/{share → agent}/tests/mcp-card.test.ts

@@ -8,15 +8,17 @@
 </MODULE_MAP>
 <CHANGE_SUMMARY>
   <item>RFC-0783: initial MCP Server Card projection tests.</item>
+  <item>RFC-1113: align agent discovery surface with RFC 9727 and MCP 2026-07-28 stateless era</item>
 </CHANGE_SUMMARY>
 */
 
 import { test, expect } from "vitest";
-import { buildMcpServerCard } from "../agent/mcp-card.ts";
-import { buildAgentSurfaceManifest } from "../agent/manifest.ts";
+import { buildMcpServerCard } from "../mcp-card.ts";
+import { buildAgentSurfaceManifest } from "../manifest.ts";
 
 test("buildMcpServerCard: null mcp → returns null", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -26,6 +28,7 @@ test("buildMcpServerCard: null mcp → returns null", () => {
 
 test("buildMcpServerCard: mcp interface → card with correct fields", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "warpgogol",
     baseUrl: "https://warpgogol.com",
     languages: { default: "de", supported: ["de"] },
@@ -49,6 +52,7 @@ test("buildMcpServerCard: determinism — same input produces identical output",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
+    generatedAt: "2026-01-01T00:00:00.000Z",
     mcp: { url: "/api/agent/mcp", protocolVersion: "2025-06-18" },
   };
   const a = buildMcpServerCard(buildAgentSurfaceManifest(input));

package/src/{share → agent}/tests/openapi.test.ts

@@ -9,15 +9,17 @@
 <CHANGE_SUMMARY>
   <item>RFC-0289: initial OpenAPI formatter tests.</item>
   <item>RFC-0954: add search path projection tests.</item>
+  <item>RFC-1113: align agent discovery surface with RFC 9727 and MCP 2026-07-28 stateless era</item>
 </CHANGE_SUMMARY>
 */
 
 import { test, expect } from "vitest";
-import { formatAgentOpenApi } from "../agent/openapi.ts";
-import { buildAgentSurfaceManifest } from "../agent/manifest.ts";
+import { formatAgentOpenApi } from "../openapi.ts";
+import { buildAgentSurfaceManifest } from "../manifest.ts";
 
 test("formatAgentOpenApi: empty manifest yields a valid document with no paths", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -33,6 +35,7 @@ test("formatAgentOpenApi: empty manifest yields a valid document with no paths",
 
 test("formatAgentOpenApi: one knowledge ref → one GET path + one component schema", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -61,6 +64,7 @@ test("formatAgentOpenApi: one action ref → one POST path with verbatim input/o
     properties: { accepted: { type: "boolean" as const } },
   };
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -84,10 +88,25 @@ test("formatAgentOpenApi: one action ref → one POST path with verbatim input/o
   expect(doc.components.schemas["lead.submit-input"]).toEqual(inputSchema);
   expect(doc.components.schemas["lead.submit-output"]).toEqual(outputSchema);
   expect(op!.requestBody!.content["application/json"].schema).toEqual(inputSchema);
+
+  // RFC-1112: Idempotency-Key header parameter.
+  const idemParam = op!.parameters!.find((p) => p.name === "Idempotency-Key");
+  expect(idemParam).toBeTruthy();
+  expect(idemParam!.in).toBe("header");
+  expect(idemParam!.required).toBe(false);
+
+  // RFC-1112: problem+json error responses + shared problem-details schema.
+  expect(doc.components.schemas["problem-details"]).toBeTruthy();
+  for (const status of ["400", "409", "413", "422", "429", "502"]) {
+    const res = op!.responses[status];
+    expect(res, `missing ${status} response`).toBeTruthy();
+    expect(res!.content?.["application/problem+json"]).toBeTruthy();
+  }
 });
 
 test("formatAgentOpenApi: an action ref without a matching capability schema is skipped defensively", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -107,6 +126,7 @@ test("formatAgentOpenApi: an action ref without a matching capability schema is
 
 test("formatAgentOpenApi: mcp interface present → x-gogol-mcp is set", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -118,6 +138,7 @@ test("formatAgentOpenApi: mcp interface present → x-gogol-mcp is set", () => {
 
 test("formatAgentOpenApi: search interface present → /api/agent/search GET path with dynamic lang enum", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de", "uk"] },
@@ -136,6 +157,7 @@ test("formatAgentOpenApi: search interface present → /api/agent/search GET pat
 
 test("formatAgentOpenApi: search interface absent → no search path", () => {
   const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
     site: "s",
     baseUrl: "https://s.example",
     languages: { default: "de", supported: ["de"] },
@@ -144,3 +166,98 @@ test("formatAgentOpenApi: search interface absent → no search path", () => {
   expect(doc.paths["/api/agent/search"]).toBe(undefined);
   expect(doc.components.schemas["search-response"]).toBe(undefined);
 });
+
+test("formatAgentOpenApi: agentGuidance renders into the operation description (RFC-1115 AC-4)", () => {
+  const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
+    site: "s",
+    baseUrl: "https://s.example",
+    languages: { default: "de", supported: ["de"] },
+    actions: [
+      {
+        id: "lead.submit",
+        url: "/api/agent/actions/lead.submit",
+        title: { de: "Anfrage senden" },
+        inputSchemaRef: "#/components/schemas/lead.submit-input",
+        entitlement: "agent.actions",
+      },
+    ],
+  });
+  const doc = formatAgentOpenApi(manifest, [
+    {
+      id: "lead.submit",
+      input: { type: "object" },
+      output: { type: "object" },
+      description: { de: "Reicht eine Kontaktanfrage ein." },
+      agentGuidance: {
+        sideEffect: "write",
+        whenToUse: "ein Besucher das Gewerbe kontaktieren will.",
+        whenNotToUse: "die Antwort bereits auf der Seite steht.",
+        retrySemantics: "mit demselben Idempotency-Key sicher wiederholbar.",
+      },
+    },
+  ]);
+  const op = doc.paths["/api/agent/actions/lead.submit"]?.post;
+  expect(op).toBeTruthy();
+  expect(op!.description).toContain("Reicht eine Kontaktanfrage ein.");
+  expect(op!.description).toContain("Use this when ein Besucher das Gewerbe kontaktieren will.");
+  expect(op!.description).toContain("Do not use this when die Antwort bereits auf der Seite steht.");
+  expect(op!.description).toContain("side effects");
+  expect(op!.description).toContain(
+    "Retry semantics: mit demselben Idempotency-Key sicher wiederholbar.",
+  );
+});
+
+test("formatAgentOpenApi: absent agentGuidance falls back to the base description (RFC-1115 AC-5)", () => {
+  const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
+    site: "s",
+    baseUrl: "https://s.example",
+    languages: { default: "de", supported: ["de"] },
+    actions: [
+      {
+        id: "lead.submit",
+        url: "/api/agent/actions/lead.submit",
+        title: { de: "Anfrage senden" },
+        inputSchemaRef: "#/components/schemas/lead.submit-input",
+        entitlement: "agent.actions",
+      },
+    ],
+  });
+  const doc = formatAgentOpenApi(manifest, [
+    {
+      id: "lead.submit",
+      input: { type: "object" },
+      output: { type: "object" },
+      description: { de: "Reicht eine Kontaktanfrage ein." },
+    },
+  ]);
+  const op = doc.paths["/api/agent/actions/lead.submit"]?.post;
+  expect(op!.description).toBe("Reicht eine Kontaktanfrage ein.");
+});
+
+test("formatAgentOpenApi: search-response schema matches the flattened citation shape (RFC-1115 AC-1)", () => {
+  const manifest = buildAgentSurfaceManifest({
+    generatedAt: "2026-01-01T00:00:00.000Z",
+    site: "s",
+    baseUrl: "https://s.example",
+    languages: { default: "de", supported: ["de"] },
+    search: { url: "/api/agent/search", model: "@cf/baai/bge-m3", dimensions: 1024 },
+  });
+  const doc = formatAgentOpenApi(manifest, []);
+  const schema = doc.components.schemas["search-response"] as {
+    properties: { results: { items: { required: string[]; properties: Record<string, unknown> } } };
+  };
+  const item = schema.properties.results.items;
+  expect(item.required).toEqual([
+    "title",
+    "canonicalUrl",
+    "updatedAt",
+    "lang",
+    "type",
+    "score",
+    "text",
+  ]);
+  expect(item.properties.canonicalUrl).toEqual({ type: "string" });
+  expect(item.properties.chunk).toBeUndefined();
+});

package/src/{share → agent}/tests/proof.test.ts

@@ -16,7 +16,7 @@ import {
   buildAgentSigningPayload,
   AGENT_PROOF_DOMAIN,
   type AgentProofArtifactKind,
-} from "../agent/proof.ts";
+} from "../proof.ts";
 
 function decodePayload(bytes: Uint8Array): string {
   return new TextDecoder().decode(bytes);

package/src/{share → attribution}/material-credits.ts

@@ -25,19 +25,19 @@ import {
   materialCreditSchema,
   materialTargetKey,
   formatMaterialCreditLine,
-} from "./schemas/material-credit.ts";
+} from "../schemas/material-credit.ts";
 
-// RFC-0488: re-export label mapping helpers for @warpgogol/werkstatt-shared/share/material-credits consumers.
+// RFC-0488: re-export label mapping helpers for @warpgogol/werkstatt-shared/attribution/material-credits consumers.
 export {
   labelForSourceType,
   labelForStatus,
   labelForUsageBasis,
-} from "./schemas/material-credit.ts";
+} from "../schemas/material-credit.ts";
 export type {
   MaterialSourceType,
   MaterialCreditStatus,
   UsageBasisType,
-} from "./schemas/material-credit.ts";
+} from "../schemas/material-credit.ts";
 
 export interface MaterialCreditRecord {
   file: string;

package/src/{share → checks}/check-hints.ts

@@ -6,7 +6,12 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>Initial implementation for check-warpgogol hints support.</item>
+  <item>RFC-1097: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
+  <item>RFC-1097: sweep — werkstatt-engine clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
 </CHANGE_SUMMARY>
 */
 

package/src/checks/index.ts

@@ -1,6 +1,6 @@
 /*
 <MODULE_CONTRACT>
-<purpose>Shared check infrastructure barrel for @warpgogol/werkstatt-shared — exports diagnosticsResult, suppressions, i18n, and astro-site-url helpers (RFC-0868).</purpose>
+<purpose>Shared checks index barrel for @warpgogol/werkstatt-shared — exports diagnosticsResult, suppressions, i18n, and astro-site-url helpers (RFC-0868).</purpose>
 <non-goals>
   <item>Do not export site-specific validators or pipeline definitions.</item>
   <item>Do not import from @warpgogol/werkstatt-site or any stack plugin.</item>
@@ -8,6 +8,9 @@
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0868: extracted from werkstatt-site/src/checks as shared infrastructure.</item>
+  <item>RFC-1097: sweep — tail packages clean
+
+Sweep batch 3: rewrote ~95 purposes across werkstatt-knowledge, werkstatt-shared, godot-game, phaser-game, lifecycle-core, projektarchiv-*, portal-*, billing-*, typescript (CONTRACT-02/PURPOSE-02). Real KEY_DECISIONS on 5 godot utils, non-goals on 5 CONTRACT-03 files, headers on 4 headerless files, CS-07 history literal fix on 2 files. Policy: vitest.config.ts + test-fixtures testPatterns, worker-configuration.d.ts excludedPath. All non-site/engine packages now 0 diagnostics.</item>
 </CHANGE_SUMMARY>
 */
 

package/src/checks/lib/astro-site-url.ts

@@ -6,7 +6,12 @@
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
-  <item>Added Compass scaffolding.</item>
+  <item>RFC-1097: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
+  <item>RFC-1097: sweep — werkstatt-engine clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
 </CHANGE_SUMMARY>
 */
 

package/src/checks/lib/i18n.ts

@@ -1,3 +1,17 @@
+/*
+<MODULE_CONTRACT>
+<purpose>i18n helpers for check validators — read the default language code from a site system.md frontmatter.</purpose>
+<non-goals>
+  <item>Do not load translation catalogs — this module only resolves the default language code.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1097: sweep — tail packages clean
+
+Sweep batch 3: rewrote ~95 purposes across werkstatt-knowledge, werkstatt-shared, godot-game, phaser-game, lifecycle-core, projektarchiv-*, portal-*, billing-*, typescript (CONTRACT-02/PURPOSE-02). Real KEY_DECISIONS on 5 godot utils, non-goals on 5 CONTRACT-03 files, headers on 4 headerless files, CS-07 history literal fix on 2 files. Policy: vitest.config.ts + test-fixtures testPatterns, worker-configuration.d.ts excludedPath. All non-site/engine packages now 0 diagnostics.</item>
+</CHANGE_SUMMARY>
+*/
+
 import { join } from "node:path";
 import { readFile } from "node:fs/promises";
 import { parse as parseYaml } from "yaml";