Clarify guide score messaging

Author: snapsynapse

ADOPTION.md

@@ -62,6 +62,11 @@ safety claim.
 A guide is not obliged to reach Level 3 in one step. Publishing at Level 1 or
 2 first is a valid and useful state.
 
+For teams seeking the highest guide-file score, the target is Level 4 of 4.
+If verifier output also says `level5_ready: true`, the guide is prepared for a
+Level 5 runtime check. The checker should not present this as `Level 4 of 5`
+or as a missing point.
+
 ## How to reach each level
 
 ### Level 1: plain text available

CHANGELOG.md

@@ -22,6 +22,8 @@ All notable changes to GuideCheck's Human-Verifiable Assistant Guide profile and
   content evaluation
 - hosted verifier result copy now surfaces Level 5 readiness without presenting
   it as achieved Level 5
+- public score language now frames Level 4 as the highest guide-file score and
+  Level 5 as separate runtime enforcement
 
 ## [0.2.1] - 2026-05-22
 

README.md

@@ -104,6 +104,10 @@ that a human can review in full before authorizing an assistant to follow it.
 - Level 5: a guide plus a conformant assistant runtime that mechanically
   enforces the execution contract
 
+Level 4 is the highest score for the guide file itself. Level 5 is not a
+higher guide-file score; it is a separate runtime enforcement claim for a
+deployment that executes a Level 4 guide.
+
 ## Local Evals
 
 Run the local regression suite with:
@@ -157,6 +161,10 @@ passes the guide-side preparation checks for runtime enforcement. This is not
 an achieved Level 5 claim; Level 5 still requires a conformant assistant
 runtime.
 
+User-facing score language should treat this as `Guide score: Level 4 of 4`
+plus `Runtime readiness: Level 5-ready`. Avoid `Level 4 of 5`, `almost Level
+5`, or similar phrasing that implies the guide file is missing a final point.
+
 Run the local reference verifier with:
 ```text
 python3 scripts/guidecheck_verify.py assistant-guide.txt --pretty

docs/index.html

@@ -619,10 +619,11 @@ <h3>Serve and verify</h3>
   <div class="container">
     <div class="demo-block">
       <h2>Verify a guide</h2>
-      <p>GuideCheck publishes a primary verifier for usability &mdash; never as the only authoritative verifier and never as a root of trust. It reports what it checked and what it did not. Optional agent and expected-level fields help identify compatibility gaps without storing full submitted URLs, prompts, model responses, IP addresses, or stable visitor identifiers as product telemetry.</p>
+      <p>GuideCheck publishes a primary verifier for usability &mdash; never as the only authoritative verifier and never as a root of trust. It reports what it checked and what it did not. Guide files score up to Level 4 of 4; Level 5 is a separate runtime enforcement claim. Optional agent and expected-level fields help identify compatibility gaps without storing full submitted URLs, prompts, model responses, IP addresses, or stable visitor identifiers as product telemetry.</p>
       <div class="demo-preview">verifier: human-verifiable-assistant-guide-verifier 0.2.1
 guide-sha256: a1b2c3 ... reviewed before use
-achieved-level: 3
+achieved-level: 4
+level5-ready: true
 findings: 0 blocking, 1 advisory
 note: conformance is not safety &mdash; read the guide</div>
       <div class="cta-row">

docs/verifier-examples.html

@@ -62,6 +62,7 @@
   <div class="container">
     <h1>Verifier Output Examples</h1>
     <p>These examples show the shape verifier authors and assistant runtimes should expect. The exact wording may differ, but the compact report and JSON output must come from the same evidence.</p>
+    <p>For a guide file, Level 4 is the highest score. A <code>level5_ready</code> value means the Level 4 guide is prepared for a separate runtime enforcement check; it is not an achieved Level 5 claim.</p>
     <p>Hosted-verifier product telemetry is separate from verifier output. It may record sanitized operational fields such as target host, path category, selected agent category, expected level, achieved level, outcome, failure category, and coarse duration, but those fields are not part of the normative verifier report consumed by an assistant runtime.</p>
 
     <h2>Passing Level 3 Compact Report</h2>

docs/verify/index.html

@@ -194,7 +194,7 @@ <h1>Verify an assistant-guide.txt file</h1>
   <div class="container">
     <div class="panel" id="verifier">
       <h2>Check a guide</h2>
-      <p>Enter the public https URL of an <code>assistant-guide.txt</code> file, or just a site URL. The hosted verifier fetches it, runs the GuideCheck checks, and reports what it found. Given a site root, it checks the standard <code>/.well-known/assistant-guide.txt</code> path. This hosted verifier evaluates Levels 1 through 4 when a guide publishes a fetchable manifest and a supported independent anchor. The optional agent and expected-level fields help identify compatibility gaps across agent families.</p>
+      <p>Enter the public https URL of an <code>assistant-guide.txt</code> file, or just a site URL. The hosted verifier fetches it, runs the GuideCheck checks, and reports what it found. Given a site root, it checks the standard <code>/.well-known/assistant-guide.txt</code> path. This hosted verifier scores guide files up to Level 4 of 4 when a guide publishes a fetchable manifest and a supported independent anchor. Level 5 is a separate runtime enforcement claim. The optional agent and expected-level fields help identify compatibility gaps across agent families.</p>
       <form id="verify-form" class="verify-form" novalidate>
         <label for="guide-url">Guide URL</label>
         <div class="verify-input-row">
@@ -272,6 +272,7 @@ <h3>Raw verifier output</h3>
       Verifier authors can also review <a href="/verifier-examples">example outputs</a>.</p>
 
     <h2>What a verifier checks</h2>
+    <p>For a guide file, Level 4 is the highest score. Level 5 is not a higher guide-file score; it is a separate claim that a conformant assistant runtime mechanically enforced a Level 4 guide during execution.</p>
     <ul>
       <li>Reachability of the guide at <code>/.well-known/assistant-guide.txt</code> and the compact verification instruction.</li>
       <li>The strict ASCII byte profile, the 8 KiB size cap, and absence of disallowed constructs.</li>
@@ -280,7 +281,7 @@ <h2>What a verifier checks</h2>
     </ul>
 
     <h2>What a verifier reports</h2>
-    <p>A GuideCheck conformance claim is valid only when backed by verifier output, the guide SHA-256, the achieved level, and the findings. For Level 4 guides, verifier output may also report <code>level5_ready</code>. That is a guide-side readiness signal, not a Level 5 runtime conformance claim.</p>
+    <p>A GuideCheck conformance claim is valid only when backed by verifier output, the guide SHA-256, the achieved level, and the findings. For Level 4 guides, verifier output may also report <code>level5_ready</code>. That means the guide has reached the highest guide-file score and is prepared for a Level 5 runtime check. It is not an achieved Level 5 claim.</p>
     <pre>verifier: human-verifiable-assistant-guide-verifier 0.2.1
 guide-url: https://example.com/.well-known/assistant-guide.txt
 guide-sha256: a1b2c3d4 ... (review the guide before use)
@@ -295,7 +296,7 @@ <h2>Conformance is not safety</h2>
     <p>A passing result, at any level, does not mean a guide is safe to follow or that its publisher is trustworthy. It means the file has the form the profile requires. Read the guide in full, apply the security practices a competent operator would already apply, and keep the human in the approval loop.</p>
 
     <h2>What this hosted verifier covers</h2>
-    <p>This hosted verifier evaluates GuideCheck Levels 1 through 4. For Level 4, it fetches the declared sidecar manifest and currently supports package-registry metadata and transparency-log anchors. It may report <code>level5_ready</code> when a Level 4 guide satisfies the guide-side runtime preparation checks. It does not yet fetch DNS TXT, repository-file, or signed <code>security.txt</code> anchors, and it does not evaluate runtime conformance (Level 5). Every hosted response carries a <code>hosted_limitations</code> field that states its scope.</p>
+    <p>This hosted verifier evaluates guide-file conformance from Level 1 through Level 4. For Level 4, it fetches the declared sidecar manifest and currently supports package-registry metadata and transparency-log anchors. It may report <code>level5_ready</code> when a Level 4 guide satisfies the guide-side runtime preparation checks. It does not yet fetch DNS TXT, repository-file, or signed <code>security.txt</code> anchors, and it does not evaluate runtime conformance (Level 5). Every hosted response carries a <code>hosted_limitations</code> field that states its scope.</p>
 
     <h2>Privacy</h2>
     <p>The guide URL you submit is sent to this site's server so it can fetch the file you named. The verifier keeps product telemetry limited to the target host, whether the path was the standard well-known path or a custom path, the selected agent category, expected level, achieved level, outcome, failure category, and coarse duration. It does not store full submitted URLs, query strings, prompts, model responses, IP addresses, or stable visitor identifiers in product telemetry. The optional agent and expected-level fields are used to find compatibility gaps, such as an agent family often expecting Level 3 but receiving Level 1. The hosting platform keeps standard short-lived request logs &mdash; timestamp, client IP, and the <code>/api/verify</code> path &mdash; for abuse prevention; those logs do not contain the guide URL.</p>

docs/verify/verify.js

@@ -137,12 +137,14 @@
     var pass = blocking === 0;
     var readiness = "";
     if (achievedLevel >= 4) {
-      readiness = guide.level5_ready ? " - Level 5-ready" : " - not Level 5-ready";
+      readiness = guide.level5_ready
+        ? " - Runtime readiness: Level 5-ready"
+        : " - Runtime readiness: not Level 5-ready";
     }
 
     headline.className = "verify-headline " + (pass ? "is-pass" : "is-fail");
     headline.textContent = pass
-      ? "Achieved Level " + achievedLevel + " · 0 blocking · " + plural(summary.warnings || 0, "warning") + readiness
+      ? "Guide score: Level " + achievedLevel + " of 4 · 0 blocking · " + plural(summary.warnings || 0, "warning") + readiness
       : "Not conformant · " + plural(blocking, "blocking finding") + " · " + plural(summary.warnings || 0, "warning") + readiness;
 
     if (data.location_note) {