semantic-js-mcp 0.10.2 → 0.10.4

package/scripts/documentation-gate-smoke.mjs

@@ -6,8 +6,9 @@ import {evaluateDocumentation} from "./documentation-gate.mjs";
 
 const headingText = (headings) => headings.map((heading) => `## ${heading}`).join("\n");
 const valid = {
-  [DOCUMENTATION_FILE.README]: `${headingText(DOCUMENTATION_REQUIREMENT.README_HEADINGS)}\n${DOCUMENTATION_REQUIREMENT.README_LINKS.map((link) => `[doc](${link})`).join("\n")}\n${DOCUMENTATION_REQUIREMENT.README_LITERALS.join("\n")}`,
-  [DOCUMENTATION_FILE.AGENT_SETUP]: `${headingText(DOCUMENTATION_REQUIREMENT.AGENT_SETUP_HEADINGS)}\n${DOCUMENTATION_REQUIREMENT.AGENT_SETUP_LITERALS.join("\n")}`,
+  [DOCUMENTATION_FILE.README]: `${headingText(DOCUMENTATION_REQUIREMENT.README_HEADINGS)}\n${DOCUMENTATION_REQUIREMENT.README_LINKS.map((link) => `[doc](${link})`).join("\n")}\n${DOCUMENTATION_REQUIREMENT.README_SETUP_ENTRY_LITERALS.join("\n")}`,
+  [DOCUMENTATION_FILE.SETUP]: `${headingText(DOCUMENTATION_REQUIREMENT.SETUP_HEADINGS)}\n${DOCUMENTATION_REQUIREMENT.SETUP_LITERALS.join("\n")}`,
+  [DOCUMENTATION_FILE.DISTRIBUTION]: `${headingText(DOCUMENTATION_REQUIREMENT.DISTRIBUTION_HEADINGS)}\n${DOCUMENTATION_REQUIREMENT.DISTRIBUTION_LITERALS.join("\n")}`,
   [DOCUMENTATION_FILE.GETTING_STARTED]: `${headingText(DOCUMENTATION_REQUIREMENT.GETTING_STARTED_HEADINGS)}\n${DOCUMENTATION_REQUIREMENT.GETTING_STARTED_LITERALS.join("\n")}`,
   [DOCUMENTATION_FILE.SEMANTIC_NAVIGATION_SKILL]: `${headingText(DOCUMENTATION_REQUIREMENT.SEMANTIC_NAVIGATION_SKILL_HEADINGS)}\n${DOCUMENTATION_REQUIREMENT.SEMANTIC_NAVIGATION_SKILL_LITERALS.join("\n")}`,
   [DOCUMENTATION_FILE.CONTRIBUTING]: "# Contributing",
@@ -16,6 +17,105 @@ const valid = {
 
 strictEqual(evaluateDocumentation(valid).length, 0, "Valid public documentation failed the gate");
 
+const lateSetupGuards = {
+  ...valid,
+  [DOCUMENTATION_FILE.SETUP]: valid[DOCUMENTATION_FILE.SETUP].replace("## Guards\n", "").concat("\n## Guards\n"),
+};
+strictEqual(
+  evaluateDocumentation(lateSetupGuards).some((finding) => finding.reason === DOCUMENTATION_REASON.SETUP_GUARDS_NOT_FIRST),
+  true,
+  "Late setup guards were accepted",
+);
+
+const fencedSetupGuards = {
+  ...valid,
+  [DOCUMENTATION_FILE.SETUP]: valid[DOCUMENTATION_FILE.SETUP].replace("## Guards\n", "```md\n## Guards\n```\n"),
+};
+strictEqual(
+  evaluateDocumentation(fencedSetupGuards).some(
+    (finding) =>
+      finding.reason === DOCUMENTATION_REASON.HEADING_MISSING &&
+      finding.file === DOCUMENTATION_FILE.SETUP &&
+      finding.heading === DOCUMENTATION_REQUIREMENT.SETUP_FIRST_SECTION,
+  ),
+  true,
+  "Setup heading inside a fenced block was accepted",
+);
+
+const invalidSetupOrder = {
+  ...valid,
+  [DOCUMENTATION_FILE.SETUP]: valid[DOCUMENTATION_FILE.SETUP]
+    .replace("## Prerequisites\n", "## Setup Order Placeholder\n")
+    .replace("## Choose A Version\n", "## Prerequisites\n")
+    .replace("## Setup Order Placeholder\n", "## Choose A Version\n"),
+};
+strictEqual(
+  evaluateDocumentation(invalidSetupOrder).some((finding) => finding.reason === DOCUMENTATION_REASON.SETUP_SECTION_ORDER_INVALID),
+  true,
+  "Invalid setup section order was accepted",
+);
+
+const earlySetupBackground = {
+  ...valid,
+  [DOCUMENTATION_FILE.SETUP]: valid[DOCUMENTATION_FILE.SETUP]
+    .replace("## Background\n", "")
+    .replace("## Troubleshooting\n", "## Background\n## Troubleshooting\n"),
+};
+strictEqual(
+  evaluateDocumentation(earlySetupBackground).some((finding) => finding.reason === DOCUMENTATION_REASON.SETUP_BACKGROUND_NOT_LAST),
+  true,
+  "Setup background outside the final section was accepted",
+);
+
+const lateSetupEntryPoint = {
+  ...valid,
+  [DOCUMENTATION_FILE.README]: valid[DOCUMENTATION_FILE.README].replace("## Setup\n", "").concat("\n## Setup\n"),
+};
+strictEqual(
+  evaluateDocumentation(lateSetupEntryPoint).some((finding) => finding.reason === DOCUMENTATION_REASON.SETUP_ENTRY_POINT_NOT_FIRST),
+  true,
+  "Late setup entry point was accepted",
+);
+
+const duplicateSetupSection = {
+  ...valid,
+  [DOCUMENTATION_FILE.README]: `${valid[DOCUMENTATION_FILE.README]}\n## ${DOCUMENTATION_REQUIREMENT.README_FORBIDDEN_SETUP_HEADINGS[1]}`,
+};
+strictEqual(
+  evaluateDocumentation(duplicateSetupSection).some((finding) => finding.reason === DOCUMENTATION_REASON.DUPLICATE_SETUP_SECTION),
+  true,
+  "Duplicate README setup section was accepted",
+);
+
+for (const literal of DOCUMENTATION_REQUIREMENT.README_FORBIDDEN_SETUP_LITERALS) {
+  const duplicateSetupCommand = {
+    ...valid,
+    [DOCUMENTATION_FILE.README]: `${valid[DOCUMENTATION_FILE.README]}\n${literal}`,
+  };
+  strictEqual(
+    evaluateDocumentation(duplicateSetupCommand).some(
+      (finding) => finding.reason === DOCUMENTATION_REASON.DUPLICATE_SETUP_COMMAND && finding.literal === literal,
+    ),
+    true,
+    `Duplicate README setup command was accepted: ${literal}`,
+  );
+}
+
+const duplicateDistributionSetupCommand = {
+  ...valid,
+  [DOCUMENTATION_FILE.DISTRIBUTION]: `${valid[DOCUMENTATION_FILE.DISTRIBUTION]}\n${DOCUMENTATION_REQUIREMENT.DISTRIBUTION_FORBIDDEN_SETUP_LITERALS[0]}`,
+};
+strictEqual(
+  evaluateDocumentation(duplicateDistributionSetupCommand).some(
+    (finding) =>
+      finding.file === DOCUMENTATION_FILE.DISTRIBUTION &&
+      finding.reason === DOCUMENTATION_REASON.DUPLICATE_SETUP_COMMAND &&
+      finding.literal === DOCUMENTATION_REQUIREMENT.DISTRIBUTION_FORBIDDEN_SETUP_LITERALS[0],
+  ),
+  true,
+  "Duplicate distribution setup command was accepted",
+);
+
 const missingHeading = {...valid, [DOCUMENTATION_FILE.README]: valid[DOCUMENTATION_FILE.README].replace("## Verification", "")};
 strictEqual(
   evaluateDocumentation(missingHeading).some((finding) => finding.reason === DOCUMENTATION_REASON.HEADING_MISSING),
@@ -48,96 +148,267 @@ strictEqual(
   "Missing canonical example literal was accepted",
 );
 
-const missingMarketplaceUpgrade = {
+const missingSetupLink = {
   ...valid,
-  [DOCUMENTATION_FILE.README]: valid[DOCUMENTATION_FILE.README].replace(DOCUMENTATION_REQUIREMENT.README_LITERALS[0], ""),
+  [DOCUMENTATION_FILE.README]: valid[DOCUMENTATION_FILE.README].replaceAll(
+    `](${DOCUMENTATION_REQUIREMENT.README_LINKS[0]})`,
+    "](missing-setup.md)",
+  ),
 };
 strictEqual(
-  evaluateDocumentation(missingMarketplaceUpgrade).some(
-    (finding) =>
-      finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING && finding.literal === DOCUMENTATION_REQUIREMENT.README_LITERALS[0],
+  evaluateDocumentation(missingSetupLink).some(
+    (finding) => finding.reason === DOCUMENTATION_REASON.LINK_MISSING && finding.link === DOCUMENTATION_REQUIREMENT.README_LINKS[0],
   ),
   true,
-  "Missing marketplace upgrade guidance was accepted",
+  "Missing setup README link was accepted",
 );
 
-const missingAgentSetupLink = {
+const missingSetupEntryInstruction = {
   ...valid,
-  [DOCUMENTATION_FILE.README]: valid[DOCUMENTATION_FILE.README].replace(`[doc](${DOCUMENTATION_REQUIREMENT.README_LINKS[0]})`, ""),
+  [DOCUMENTATION_FILE.README]: valid[DOCUMENTATION_FILE.README].replace(DOCUMENTATION_REQUIREMENT.README_SETUP_ENTRY_LITERALS[0], ""),
 };
 strictEqual(
-  evaluateDocumentation(missingAgentSetupLink).some(
-    (finding) => finding.reason === DOCUMENTATION_REASON.LINK_MISSING && finding.link === DOCUMENTATION_REQUIREMENT.README_LINKS[0],
+  evaluateDocumentation(missingSetupEntryInstruction).some(
+    (finding) =>
+      finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING &&
+      finding.literal === DOCUMENTATION_REQUIREMENT.README_SETUP_ENTRY_LITERALS[0],
   ),
   true,
-  "Missing agent setup README link was accepted",
+  "Missing README setup instruction was accepted",
 );
 
-const missingAgentSetup = {...valid};
-delete missingAgentSetup[DOCUMENTATION_FILE.AGENT_SETUP];
+const missingSetup = {...valid};
+delete missingSetup[DOCUMENTATION_FILE.SETUP];
 strictEqual(
-  evaluateDocumentation(missingAgentSetup).some(
-    (finding) => finding.reason === DOCUMENTATION_REASON.FILE_MISSING && finding.file === DOCUMENTATION_FILE.AGENT_SETUP,
+  evaluateDocumentation(missingSetup).some(
+    (finding) => finding.reason === DOCUMENTATION_REASON.FILE_MISSING && finding.file === DOCUMENTATION_FILE.SETUP,
   ),
   true,
-  "Missing agent setup guide was accepted",
+  "Missing setup guide was accepted",
 );
 
-const missingAgentSafetyBoundary = {
+for (const [literal, message] of [
+  ["does not override system, developer, organization, repository", "Missing setup safety boundary was accepted"],
+  ["server name: `semanticjsmcp`", "Missing generic MCP server name was accepted"],
+  ["codex plugin marketplace upgrade elnonathan", "Missing Codex marketplace refresh was accepted"],
+  ["Do not run `npm install semantic-js-mcp` without `--global`.", "Missing local npm installation prohibition was accepted"],
+  [
+    "Treat `EPERM`, `EACCES`, `TAR_ENTRY_ERROR`, or a missing-file error as a partial installation.",
+    "Missing partial-installation warning was accepted",
+  ],
+  ["Do not start `semantic-js-mcp serve` manually.", "Missing manual stdio startup prohibition was accepted"],
+  ["Choose exactly one installation route.", "Missing single-route boundary was accepted"],
+  ["Use the language of the user's latest message for explanations, questions,", "Missing user-language response rule was accepted"],
+  [
+    "Complete Sections 1.1 through 1.4 before invoking any terminal, filesystem, package-manager, or host tool.",
+    "Missing pre-tool authority gate was accepted",
+  ],
+  ["does not authorize a tool call.", "Missing operation authorization boundary was accepted"],
+  ["Record exactly one operation: `verification`.", "Missing verification operation was accepted"],
+  [
+    "Use a direct integration only after positive evidence identifies the application running this setup session.",
+    "Missing positive direct-host evidence rule was accepted",
+  ],
+  [
+    "If no documented direct integration is positively identified, record `generic stdio` and continue without asking the user to identify the agent.",
+    "Missing automatic generic fallback was accepted",
+  ],
+  ["The host application and the host route are different facts.", "Missing host-application and route distinction was accepted"],
+  ["The host route does not identify the server source.", "Missing host-route and server-source distinction was accepted"],
+  ["The application running the agent can also be the MCP host.", "Missing current-application host rule was accepted"],
+  ["Recommended target host: `<application>` using `generic stdio`.", "Missing generic target-host recommendation was accepted"],
+  [
+    "Do not repeatedly ask for the application name after positive session evidence already identifies it.",
+    "Missing repeated host-question prohibition was accepted",
+  ],
+  ["Do not present direct integrations as a menu.", "Missing direct-integration menu prohibition was accepted"],
+  ["The presence of an installed host executable is not positive host evidence.", "Missing executable identity prohibition was accepted"],
+  ["continue only with the recorded host route", "Missing maintenance host-route guard was accepted"],
+  ["and server source for the existing installation.", "Missing maintenance server-source guard was accepted"],
+  [
+    "Do not use `npx`, `npm exec`, `@latest`, or an npm cache as an installation route.",
+    "Missing ephemeral installation prohibition was accepted",
+  ],
+  ["Do not pipe JSON-RPC messages", "Missing manual JSON-RPC prohibition was accepted"],
+  [
+    "A manually started server does not prove that the configured host application loaded the MCP tools.",
+    "Missing host-integration proof boundary was accepted",
+  ],
+  ["Source checkout registration is not supported", "Missing Codex source-checkout boundary was accepted"],
+  ["When the recorded host route is `Codex direct`, the agent may run the", "Missing Codex prerequisite command ownership was accepted"],
+  [
+    "I cannot identify the current host application. Which application should I configure?",
+    "Missing unknown-host configuration question was accepted",
+  ],
+  ["record `user` as the command runner.", "Missing generic command-runner record was accepted"],
+  ["low side-effect risk, but they are not sandbox-neutral evidence:", "Missing sandbox-neutral version-check boundary was accepted"],
+  ["The agent must not perform even read-only local checks.", "Missing generic local-inspection prohibition was accepted"],
+  ["A command name is not enough to infer its argument grammar.", "Missing host-command grammar guard was accepted"],
+  ["Do not construct the add command unless Section 5.1 recorded its exact current", "Missing add-command grammar checkpoint was accepted"],
+  ["An added-entry message is not enough.", "Missing saved-entry validation guard was accepted"],
+  ["A host status of `failed` is a failure, not an expected pre-restart state.", "Missing failed-host-status guard was accepted"],
+  ["Use `lsp_document_symbols` on that file as the first functional", "Missing bounded functional-test guidance was accepted"],
+  ["global executable checks for a source checkout.", "Missing source-checkout verification boundary was accepted"],
+  ["search the user's home directory or unrelated directories for a checkout.", "Missing source-checkout search prohibition was accepted"],
+  [
+    "A similarly named file is not evidence of a Semantic JS MCP installation.",
+    "Missing similarly-named-file evidence boundary was accepted",
+  ],
+  ["Before constructing a removal command, confirm the exact remove subcommand", "Missing removal-command grammar guard was accepted"],
+  ["do not run the global npm", "Missing source-checkout removal boundary was accepted"],
+  [
+    "Before constructing a source-checkout registration command, confirm the exact",
+    "Missing source-checkout registration grammar guard was accepted",
+  ],
+  ["report that the source checkout is ready and stop.", "Missing no-host source-checkout outcome was accepted"],
+  ["No source-code call is required", "Missing installation authority boundary was accepted"],
+]) {
+  const missingInstruction = {
+    ...valid,
+    [DOCUMENTATION_FILE.SETUP]: valid[DOCUMENTATION_FILE.SETUP].replace(literal, ""),
+  };
+  strictEqual(
+    evaluateDocumentation(missingInstruction).some(
+      (finding) => finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING && finding.literal === literal,
+    ),
+    true,
+    message,
+  );
+}
+
+const missingCombinationInvariant = {
   ...valid,
-  [DOCUMENTATION_FILE.AGENT_SETUP]: valid[DOCUMENTATION_FILE.AGENT_SETUP].replace(DOCUMENTATION_REQUIREMENT.AGENT_SETUP_LITERALS[2], ""),
+  [DOCUMENTATION_FILE.SEMANTIC_NAVIGATION_SKILL]: valid[DOCUMENTATION_FILE.SEMANTIC_NAVIGATION_SKILL].replace(
+    DOCUMENTATION_REQUIREMENT.SEMANTIC_NAVIGATION_SKILL_LITERALS[1],
+    "",
+  ),
 };
 strictEqual(
-  evaluateDocumentation(missingAgentSafetyBoundary).some(
+  evaluateDocumentation(missingCombinationInvariant).some(
     (finding) =>
-      finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING && finding.literal === DOCUMENTATION_REQUIREMENT.AGENT_SETUP_LITERALS[2],
+      finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING &&
+      finding.literal === DOCUMENTATION_REQUIREMENT.SEMANTIC_NAVIGATION_SKILL_LITERALS[1],
   ),
   true,
-  "Missing agent setup safety boundary was accepted",
+  "Missing combination-invariant guidance was accepted",
 );
 
-const missingGenericServerName = {
+const missingDiagnosticExampleGuidance = {
   ...valid,
-  [DOCUMENTATION_FILE.AGENT_SETUP]: valid[DOCUMENTATION_FILE.AGENT_SETUP].replace(DOCUMENTATION_REQUIREMENT.AGENT_SETUP_LITERALS[4], ""),
+  [DOCUMENTATION_FILE.GETTING_STARTED]: valid[DOCUMENTATION_FILE.GETTING_STARTED].replace(
+    DOCUMENTATION_REQUIREMENT.GETTING_STARTED_LITERALS[3],
+    "",
+  ),
 };
 strictEqual(
-  evaluateDocumentation(missingGenericServerName).some(
+  evaluateDocumentation(missingDiagnosticExampleGuidance).some(
     (finding) =>
-      finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING && finding.literal === DOCUMENTATION_REQUIREMENT.AGENT_SETUP_LITERALS[4],
+      finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING && finding.literal === DOCUMENTATION_REQUIREMENT.GETTING_STARTED_LITERALS[3],
   ),
   true,
-  "Missing generic MCP server name was accepted",
+  "Missing untrusted-diagnostic example guidance was accepted",
 );
 
-const missingCombinationInvariant = {
+const missingDiagnosticSkillGuidance = {
   ...valid,
   [DOCUMENTATION_FILE.SEMANTIC_NAVIGATION_SKILL]: valid[DOCUMENTATION_FILE.SEMANTIC_NAVIGATION_SKILL].replace(
-    DOCUMENTATION_REQUIREMENT.SEMANTIC_NAVIGATION_SKILL_LITERALS[1],
+    DOCUMENTATION_REQUIREMENT.SEMANTIC_NAVIGATION_SKILL_LITERALS[4],
     "",
   ),
 };
 strictEqual(
-  evaluateDocumentation(missingCombinationInvariant).some(
+  evaluateDocumentation(missingDiagnosticSkillGuidance).some(
     (finding) =>
       finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING &&
-      finding.literal === DOCUMENTATION_REQUIREMENT.SEMANTIC_NAVIGATION_SKILL_LITERALS[1],
+      finding.literal === DOCUMENTATION_REQUIREMENT.SEMANTIC_NAVIGATION_SKILL_LITERALS[4],
   ),
   true,
-  "Missing combination-invariant guidance was accepted",
+  "Missing unconfirmed-diagnostic skill guidance was accepted",
+);
+
+const missingTrustedPublishingPolicy = {
+  ...valid,
+  [DOCUMENTATION_FILE.DISTRIBUTION]: valid[DOCUMENTATION_FILE.DISTRIBUTION].replace(DOCUMENTATION_REQUIREMENT.DISTRIBUTION_LITERALS[2], ""),
+};
+strictEqual(
+  evaluateDocumentation(missingTrustedPublishingPolicy).some(
+    (finding) =>
+      finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING && finding.literal === DOCUMENTATION_REQUIREMENT.DISTRIBUTION_LITERALS[2],
+  ),
+  true,
+  "Missing trusted-publishing policy was accepted",
+);
+
+const missingPostpublicationOrder = {
+  ...valid,
+  [DOCUMENTATION_FILE.DISTRIBUTION]: valid[DOCUMENTATION_FILE.DISTRIBUTION].replace(DOCUMENTATION_REQUIREMENT.DISTRIBUTION_LITERALS[5], ""),
+};
+strictEqual(
+  evaluateDocumentation(missingPostpublicationOrder).some(
+    (finding) =>
+      finding.reason === DOCUMENTATION_REASON.LITERAL_MISSING && finding.literal === DOCUMENTATION_REQUIREMENT.DISTRIBUTION_LITERALS[5],
+  ),
+  true,
+  "Missing postpublication order was accepted",
 );
 
 process.stdout.write(
   `${JSON.stringify(
     {
       validDocumentation: "pass",
+      lateSetupGuards: "rejected",
+      fencedSetupGuards: "rejected",
+      invalidSetupOrder: "rejected",
+      earlySetupBackground: "rejected",
+      lateSetupEntryPoint: "rejected",
+      duplicateSetupSection: "rejected",
+      duplicateSetupCommand: "rejected",
+      duplicateDistributionSetupCommand: "rejected",
       missingHeading: "rejected",
       missingLiteral: "rejected",
-      missingMarketplaceUpgrade: "rejected",
-      missingAgentSetupLink: "rejected",
-      missingAgentSetup: "rejected",
-      missingAgentSafetyBoundary: "rejected",
+      missingSetupLink: "rejected",
+      missingSetupEntryInstruction: "rejected",
+      missingSetup: "rejected",
+      missingSetupSafetyBoundary: "rejected",
       missingGenericServerName: "rejected",
+      missingUserLanguageResponseRule: "rejected",
+      missingCodexMarketplaceRefresh: "rejected",
+      missingPreToolAuthorityGate: "rejected",
+      missingOperationAuthorizationBoundary: "rejected",
+      missingVerificationOperation: "rejected",
+      missingPositiveDirectHostEvidence: "rejected",
+      missingAutomaticGenericFallback: "rejected",
+      missingHostApplicationRouteDistinction: "rejected",
+      missingHostRouteServerSourceDistinction: "rejected",
+      missingCurrentApplicationHostRule: "rejected",
+      missingGenericTargetHostRecommendation: "rejected",
+      missingRepeatedHostQuestionProhibition: "rejected",
+      missingDirectIntegrationMenuProhibition: "rejected",
+      missingExecutableIdentityProhibition: "rejected",
+      missingMaintenanceRouteOwnershipGuard: "rejected",
+      missingEphemeralInstallationProhibition: "rejected",
+      missingManualJsonRpcProhibition: "rejected",
+      missingHostIntegrationProofBoundary: "rejected",
+      missingGenericConfigurationQuestion: "rejected",
+      missingGenericCommandRunnerRecord: "rejected",
+      missingSandboxNeutralVersionCheckBoundary: "rejected",
+      missingGenericLocalInspectionProhibition: "rejected",
+      missingHostCommandGrammarGuard: "rejected",
+      missingAddCommandGrammarCheckpoint: "rejected",
+      missingSavedEntryValidationGuard: "rejected",
+      missingFailedHostStatusGuard: "rejected",
+      missingBoundedFunctionalTestGuidance: "rejected",
+      missingSourceCheckoutVerificationBoundary: "rejected",
+      missingSourceCheckoutSearchProhibition: "rejected",
+      missingSimilarlyNamedFileEvidenceBoundary: "rejected",
+      missingRemovalCommandGrammarGuard: "rejected",
+      missingSourceCheckoutRemovalBoundary: "rejected",
+      missingSourceCheckoutRegistrationGrammarGuard: "rejected",
       missingCombinationInvariant: "rejected",
+      missingDiagnosticExampleGuidance: "rejected",
+      missingDiagnosticSkillGuidance: "rejected",
+      missingTrustedPublishingPolicy: "rejected",
+      missingPostpublicationOrder: "rejected",
       privateCoordination: "rejected",
     },
     null,

package/scripts/documentation-gate.mjs

@@ -13,15 +13,49 @@ import {
   PUBLIC_ROOT_DOCUMENT,
 } from "./documentation-contract.mjs";
 
+function markdownStructuralLines(source) {
+  const lines = [];
+  let fence;
+  for (const line of source.split("\n")) {
+    const match = /^\s{0,3}(`{3,}|~{3,})(.*)$/.exec(line);
+    if (match && fence === undefined) {
+      fence = {marker: match[1][0], length: match[1].length};
+      continue;
+    }
+    if (match && match[1][0] === fence?.marker && match[1].length >= fence.length && match[2].trim() === "") {
+      fence = undefined;
+      continue;
+    }
+    if (fence === undefined) lines.push(line);
+  }
+  return lines;
+}
+
 function markdownHeadings(source) {
   return new Set(
-    source
-      .split("\n")
+    markdownStructuralLines(source)
       .map((line) => /^#{1,6}\s+(.+?)\s*$/.exec(line)?.[1])
       .filter(Boolean),
   );
 }
 
+function levelTwoHeadings(source) {
+  return markdownStructuralLines(source)
+    .map((line) => /^##\s+(.+?)\s*$/.exec(line)?.[1])
+    .filter(Boolean);
+}
+
+function requiredHeadingsAreOrdered(source, requiredHeadings) {
+  const headings = levelTwoHeadings(source);
+  let nextIndex = 0;
+  for (const requiredHeading of requiredHeadings) {
+    const index = headings.indexOf(requiredHeading, nextIndex);
+    if (index === -1) return false;
+    nextIndex = index + 1;
+  }
+  return true;
+}
+
 function repositoryPath(root, absolute) {
   return path.relative(root, absolute).split(path.sep).join("/");
 }
@@ -35,7 +69,8 @@ export function evaluateDocumentation(documents) {
 
   const headingRequirements = [
     [DOCUMENTATION_FILE.README, DOCUMENTATION_REQUIREMENT.README_HEADINGS],
-    [DOCUMENTATION_FILE.AGENT_SETUP, DOCUMENTATION_REQUIREMENT.AGENT_SETUP_HEADINGS],
+    [DOCUMENTATION_FILE.SETUP, DOCUMENTATION_REQUIREMENT.SETUP_HEADINGS],
+    [DOCUMENTATION_FILE.DISTRIBUTION, DOCUMENTATION_REQUIREMENT.DISTRIBUTION_HEADINGS],
     [DOCUMENTATION_FILE.GETTING_STARTED, DOCUMENTATION_REQUIREMENT.GETTING_STARTED_HEADINGS],
     [DOCUMENTATION_FILE.SEMANTIC_NAVIGATION_SKILL, DOCUMENTATION_REQUIREMENT.SEMANTIC_NAVIGATION_SKILL_HEADINGS],
   ];
@@ -50,14 +85,30 @@ export function evaluateDocumentation(documents) {
 
   const readme = documents[DOCUMENTATION_FILE.README];
   if (readme !== undefined) {
+    if (levelTwoHeadings(readme)[0] !== DOCUMENTATION_REQUIREMENT.README_FIRST_SECTION) {
+      findings.push({
+        file: DOCUMENTATION_FILE.README,
+        reason: DOCUMENTATION_REASON.SETUP_ENTRY_POINT_NOT_FIRST,
+        expectedHeading: DOCUMENTATION_REQUIREMENT.README_FIRST_SECTION,
+      });
+    }
     for (const link of DOCUMENTATION_REQUIREMENT.README_LINKS) {
       if (readme.includes(`](${link})`)) continue;
       findings.push({file: DOCUMENTATION_FILE.README, reason: DOCUMENTATION_REASON.LINK_MISSING, link});
     }
-    for (const literal of DOCUMENTATION_REQUIREMENT.README_LITERALS) {
+    for (const literal of DOCUMENTATION_REQUIREMENT.README_SETUP_ENTRY_LITERALS) {
       if (readme.includes(literal)) continue;
       findings.push({file: DOCUMENTATION_FILE.README, reason: DOCUMENTATION_REASON.LITERAL_MISSING, literal});
     }
+    const readmeHeadings = markdownHeadings(readme);
+    for (const heading of DOCUMENTATION_REQUIREMENT.README_FORBIDDEN_SETUP_HEADINGS) {
+      if (!readmeHeadings.has(heading)) continue;
+      findings.push({file: DOCUMENTATION_FILE.README, reason: DOCUMENTATION_REASON.DUPLICATE_SETUP_SECTION, heading});
+    }
+    for (const literal of DOCUMENTATION_REQUIREMENT.README_FORBIDDEN_SETUP_LITERALS) {
+      if (!readme.includes(literal)) continue;
+      findings.push({file: DOCUMENTATION_FILE.README, reason: DOCUMENTATION_REASON.DUPLICATE_SETUP_COMMAND, literal});
+    }
   }
 
   const gettingStarted = documents[DOCUMENTATION_FILE.GETTING_STARTED];
@@ -68,11 +119,32 @@ export function evaluateDocumentation(documents) {
     }
   }
 
-  const agentSetup = documents[DOCUMENTATION_FILE.AGENT_SETUP];
-  if (agentSetup !== undefined) {
-    for (const literal of DOCUMENTATION_REQUIREMENT.AGENT_SETUP_LITERALS) {
-      if (agentSetup.includes(literal)) continue;
-      findings.push({file: DOCUMENTATION_FILE.AGENT_SETUP, reason: DOCUMENTATION_REASON.LITERAL_MISSING, literal});
+  const setup = documents[DOCUMENTATION_FILE.SETUP];
+  if (setup !== undefined) {
+    const setupHeadings = levelTwoHeadings(setup);
+    if (setupHeadings[0] !== DOCUMENTATION_REQUIREMENT.SETUP_FIRST_SECTION) {
+      findings.push({
+        file: DOCUMENTATION_FILE.SETUP,
+        reason: DOCUMENTATION_REASON.SETUP_GUARDS_NOT_FIRST,
+        expectedHeading: DOCUMENTATION_REQUIREMENT.SETUP_FIRST_SECTION,
+      });
+    }
+    if (!requiredHeadingsAreOrdered(setup, DOCUMENTATION_REQUIREMENT.SETUP_HEADINGS)) {
+      findings.push({
+        file: DOCUMENTATION_FILE.SETUP,
+        reason: DOCUMENTATION_REASON.SETUP_SECTION_ORDER_INVALID,
+      });
+    }
+    if (setupHeadings.at(-1) !== DOCUMENTATION_REQUIREMENT.SETUP_LAST_SECTION) {
+      findings.push({
+        file: DOCUMENTATION_FILE.SETUP,
+        reason: DOCUMENTATION_REASON.SETUP_BACKGROUND_NOT_LAST,
+        expectedHeading: DOCUMENTATION_REQUIREMENT.SETUP_LAST_SECTION,
+      });
+    }
+    for (const literal of DOCUMENTATION_REQUIREMENT.SETUP_LITERALS) {
+      if (setup.includes(literal)) continue;
+      findings.push({file: DOCUMENTATION_FILE.SETUP, reason: DOCUMENTATION_REASON.LITERAL_MISSING, literal});
     }
   }
 
@@ -88,6 +160,18 @@ export function evaluateDocumentation(documents) {
     }
   }
 
+  const distribution = documents[DOCUMENTATION_FILE.DISTRIBUTION];
+  if (distribution !== undefined) {
+    for (const literal of DOCUMENTATION_REQUIREMENT.DISTRIBUTION_LITERALS) {
+      if (distribution.includes(literal)) continue;
+      findings.push({file: DOCUMENTATION_FILE.DISTRIBUTION, reason: DOCUMENTATION_REASON.LITERAL_MISSING, literal});
+    }
+    for (const literal of DOCUMENTATION_REQUIREMENT.DISTRIBUTION_FORBIDDEN_SETUP_LITERALS) {
+      if (!distribution.includes(literal)) continue;
+      findings.push({file: DOCUMENTATION_FILE.DISTRIBUTION, reason: DOCUMENTATION_REASON.DUPLICATE_SETUP_COMMAND, literal});
+    }
+  }
+
   for (const [file, source] of Object.entries(documents)) {
     if (PRIVATE_COORDINATION_PATTERN.test(source)) {
       findings.push({file, reason: DOCUMENTATION_REASON.PRIVATE_COORDINATION});

package/scripts/generate-protocol-reference.mjs

@@ -21,9 +21,11 @@ import {
   DEFINITION_SELECTION_STATUS,
   DIAGNOSTIC_EVIDENCE_REASON,
   DIAGNOSTIC_FRESHNESS,
+  DIAGNOSTIC_GUIDANCE,
   DIAGNOSTIC_LANGUAGE,
   DIAGNOSTIC_PROVIDER,
   DIAGNOSTIC_REGION,
+  DIAGNOSTIC_RESULT_FIELD,
   DIAGNOSTIC_SEVERITY,
   DOCTOR_CHECK,
   DOCTOR_DISTRIBUTION_ACCEPTED_STATUS,
@@ -131,6 +133,8 @@ const content =
     section("Diagnostic Language", DIAGNOSTIC_LANGUAGE),
     section("Diagnostic Severity", DIAGNOSTIC_SEVERITY),
     section("Diagnostic Evidence Reason", DIAGNOSTIC_EVIDENCE_REASON),
+    section("Diagnostic Result Fields", DIAGNOSTIC_RESULT_FIELD),
+    section("Diagnostic Guidance", DIAGNOSTIC_GUIDANCE),
     section("Evidence Status", EVIDENCE_STATUS),
     section("Reference Content Freshness", CONTENT_FRESHNESS),
     section("Error Code", ERROR_CODE),

package/scripts/negative-verification-smoke.mjs

@@ -163,6 +163,10 @@ try {
   const diagnostics = result(await client.callTool({name: TOOL.DIAGNOSTICS, arguments: {file: target, root: workspace}}), TOOL.DIAGNOSTICS);
   if (diagnostics.result.evidence.status === EVIDENCE_STATUS.UNTRUSTED) {
     assert(diagnostics.collection.status === COLLECTION_STATUS.PARTIAL, "Untrusted diagnostics claimed complete collection");
+    assert(
+      diagnostics.result.diagnosticUse?.usableAsCurrentDocumentDiagnosticEvidence === false,
+      "Untrusted diagnostics claimed usability as current-document evidence",
+    );
     assert(
       Object.values(DIAGNOSTIC_EVIDENCE_REASON).includes(diagnostics.result.evidence.reason),
       "Untrusted diagnostics used a non-canonical reason",
@@ -224,6 +228,7 @@ try {
             observed: {
               collectionStatus: diagnostics.collection.status,
               evidenceStatus: diagnostics.result.evidence.status,
+              usableAsCurrentDocumentDiagnosticEvidence: diagnostics.result.diagnosticUse.usableAsCurrentDocumentDiagnosticEvidence,
             },
             expected: {
               collectionStatus: