Status: released profile 2.0.0. Legacy contracts remain available in the repository root and prior release tags. # GuideCheck Verifier Conformance Profile ## 1. Purpose This specification defines the GuideCheck Verifier Conformance Profile for tools that evaluate `assistant-guide.txt` artifacts against the Human-Verifiable Assistant Guide profile. A conformant verifier answers four questions: - What bytes were evaluated? - What conformance level did those bytes achieve? - What evidence supports that result? - What findings must the human or assistant address before acting? This profile defines verifier behavior. It does not define a registry of approved verifier implementations. ## 2. Relationship to the Guide Profile The guide profile defines `assistant-guide.txt`, its conformance levels, action blocks, provenance model, and Level 5 runtime requirements. This verifier profile defines how a verifier checks those requirements and reports evidence. A conformant verifier is an implementation that satisfies this profile for a declared guide-profile version and passes the corresponding fixture suite. The verifier profile is intentionally implementation-neutral. A verifier may be a hosted web service, CLI, library, GitHub Action, CI job, browser extension, or assistant-runtime component. ## 3. Terminology Guide profile : The Human-Verifiable Assistant Guide profile. Verifier profile : This document. Verifier : A tool that evaluates guide bytes and emits conformance evidence. Conformant verifier : A verifier that satisfies this profile and passes the fixture suite for the applicable profile version. Finding : A machine-readable and human-readable report item describing an error, warning, or informational observation. Blocking finding : A finding with severity `error`; it blocks the claimed conformance level. Fixture suite : The official test corpus of valid and invalid guides, manifests, anchors, fetch scenarios, and expected findings. Standard primary verifier : A verifier URL published by the standards project for a specific verifier-profile version as the default hosted conformance checker. It is not the only conformant verifier and is not an oracle, but it is exempt from off-domain recommended-verifier warnings. For verifier-profile version 1.0.x the designated standard primary verifier is `https://guidecheck.org/verify`, published by the PAICE Foundation. ## 4. Scope This profile defines two evaluation modes. Public-web mode is the primary mode. The input is an HTTPS URL to an `assistant-guide.txt` resource. The verifier performs all fetches, header checks, cross-channel anchor checks, redirect handling, and TLS validation defined in this profile. Local-file mode is a normative extension. The input is a path to a local `assistant-guide.txt` file plus an optional path to a sidecar manifest. The verifier performs all byte-level, content, action-block, approval, command, prohibited-pattern, status, and staleness checks. The verifier MUST skip checks that depend on a live HTTP fetch (HTTP headers, redirect chain, TLS validation, content-variation re-fetch, hosted-verifier SSRF checks). Local-file mode MAY skip cross-channel anchor checks when the verifier has no network access; when network access is available the verifier SHOULD still resolve DNS TXT, registry, repository, and signed security.txt anchors named in metadata. A verifier MUST report the mode it ran in (`evaluation_mode: public-web` or `evaluation_mode: local-file`). A local-file evaluation MUST NOT report an achieved level higher than Level 3 unless the verifier also fetches and verifies the manifest and at least one independent cross-channel anchor; the level rules of section 25 still apply, but the absence of fetch evidence prevents Level 4 from being asserted on local bytes alone. Private-repository mode, offline-archive mode, and any other input modes remain implementation extensions outside this profile. ## 5. Non-Goals This profile does not: - certify that a guide is safe to follow - certify publisher identity, intent, or trustworthiness - execute commands or simulate command effects - audit the underlying software being installed - replace package manager trust policy, signing, SBOMs, vulnerability scanning, sandboxing, or human review - define a central registry of verifier implementations - require use of any specific hosted verifier ## 6. Verifier Threat Model A verifier MUST treat every guide, manifest, URL, redirect, DNS response, repository file, registry record, and cross-channel anchor as potentially malicious. In-scope verifier threats include: - server-side request forgery against hosted verifiers - DNS rebinding or private-network resolution - redirects to unintended hosts - TLS failure or downgrade - oversized responses and decompression bombs - content-type confusion - malicious guide text attempting to instruct the verifier - crafted metadata values carrying instructions as data - hash mismatches across same-origin and independent channels - malformed action blocks that confuse parsers - stale or revoked guides - denial-of-service through slow responses, long redirect chains, or many anchors Out-of-scope verifier threats include: - compromise of the verifier host or binary - compromise of every independent control plane used for provenance - malicious fixture-suite maintainers - attacks against the human outside the verifier output - runtime behavior after verification, except where the verifier is also a Level 5 assistant runtime ## 7. Required Safety Invariants A conformant verifier MUST: - never execute commands from the guide - never evaluate guide text as instructions to the verifier - never render Markdown, HTML, CSS, JavaScript, SVG, images, or rich media from the guide - preserve and hash the exact fetched bytes before normalization - enforce response size, timeout, redirect, and network-target limits - report findings from evidence, not from model interpretation alone - produce machine-readable output and human-readable output from the same evidence - make its verifier name, version, guide-profile version, and verifier-profile version available in output ## 8. Input Model A conformant verifier MUST accept an HTTPS URL as its primary public-web input. The verifier MAY accept optional expected values: - expected canonical URL - expected guide SHA-256 - expected guide-profile version - expected maximum conformance level to evaluate - expected verifier-profile version - standard primary verifier URL for the profile version, when configured The verifier MUST NOT require credentials, cookies, browser session state, or user-specific headers to fetch a public guide. If authentication is needed, the input is outside public-web conformance for this profile. ## 9. Fetch Requirements For public-web verification, the verifier MUST: - fetch without executing scripts - use HTTPS - validate TLS - reject plaintext HTTP for all levels above Level 0 - reject TLS certificate errors - send no cookies or ambient browser credentials - send no authorization headers unless operating in an explicitly non-public extension mode - limit redirects to a small finite count, default 5 - report every redirect hop - treat cross-origin redirects as findings - treat cross-registered-domain redirects as blocking for Level 2 and above - preserve final URL and original requested URL - record HTTP status code and response headers - reject compressed or transferred responses that expand beyond the verifier's configured maximum - stop reading once enough bytes have been read to prove the guide exceeds the maximum file size - use a simple, reproducible request profile that avoids content negotiation where practical Hosted or other public request-proxy verifiers SHOULD enforce a per-request outbound fetch budget across guide, variation, manifest, and anchor fetches, and SHOULD deduplicate exact same-URL same-profile fetches within one verification request. The verifier SHOULD use conservative timeouts: - DNS lookup timeout: default 5 seconds - connection timeout: default 10 seconds - total fetch timeout: default 30 seconds - response body read limit: at least 8193 bytes for Level 2+ evaluation, so oversize can be detected Timeouts and read limits MUST be reported. The verifier SHOULD perform a content-variation check by re-fetching once with a different harmless user agent or accept profile. If the guide bytes differ, the verifier SHOULD emit a warning and SHOULD fail Level 4 unless the manifest and independent anchors identify exactly one byte sequence as canonical. ## 10. Hosted Verifier Network Safety A hosted verifier that fetches user-supplied URLs MUST implement SSRF defenses. It MUST reject or block requests to: - localhost names, including `localhost` - loopback ranges, including `127.0.0.0/8` and `::1` - private IPv4 ranges, including `10.0.0.0/8`, `172.16.0.0/12`, and `192.168.0.0/16` - link-local ranges, including `169.254.0.0/16` and `fe80::/10` - unique local IPv6 addresses, including `fc00::/7` - multicast and unspecified addresses - cloud metadata services, including `169.254.169.254` - `.local` and other local-only names when resolvable only inside a private network It MUST re-check resolved IP addresses after redirects. It SHOULD pin the resolved address for each outbound connection to reduce DNS rebinding exposure. It SHOULD perform the final private-network check after DNS resolution and before connection. It MUST NOT expose raw fetch errors containing internal network details to untrusted users. ## 11. Byte Handling The verifier MUST compute SHA-256 over the exact fetched bytes. For Level 2 and above, the verifier MUST check: - allowed bytes are only `0x0A` and `0x20` through `0x7E` - file size is at most 8192 bytes - each line is at most 120 bytes - line count is at most 400 - line endings are LF only - no tabs - no carriage returns - no NUL bytes - no ANSI escape bytes - no Unicode bidi controls - no zero-width characters - no control characters other than LF The verifier MUST report byte offsets or line and column numbers for byte-profile failures when practical. The verifier MUST NOT normalize line endings, decode HTML entities, strip comments, render Markdown, or otherwise transform guide bytes before checking byte-profile conformance. ## 12. Content-Type and HTTP Header Checks For served guides, the verifier MUST report: - `Content-Type` - `X-Content-Type-Options` - `Strict-Transport-Security` - `Content-Length`, when present - final URL - redirect chain - TLS status For Level 2 and above: - `Content-Type: text/plain; charset=utf-8` is expected - missing or incompatible `Content-Type` is a warning unless the profile version being evaluated makes it blocking - `X-Content-Type-Options: nosniff` is expected when hosting supports it - HSTS is expected when hosting supports it The verifier MUST NOT infer safety from headers alone. ## 13. Plain-Text Parsing Rules The verifier MUST parse guides as raw plain text. The verifier MUST NOT render Markdown. The verifier MUST detect disallowed constructs from the guide profile, including: - HTML - CSS - JavaScript - Markdown images - remote embeds - data URLs - rich-document constructs - terminal escape sequences - encoded or obfuscated command blobs intended for execution - instructions to decode and execute hidden content Detection MAY include heuristic warnings for prose patterns. Heuristic warnings MUST be labeled as warnings unless the underlying rule is exact and blocking. ## 14. Metadata Parsing The verifier MUST parse the metadata block by exact fence match: ```text [assistant-guide-metadata] ... [/assistant-guide-metadata] ``` The verifier MUST require exactly one metadata block for Level 3 and above. The verifier MUST reject metadata blocks with: - missing closing fence - nested metadata fences - duplicate required keys - malformed `key: value` lines - keys outside lowercase ASCII letters, digits, and hyphens - values outside the guide byte profile The verifier MUST check Level 3 required fields: - `identifier` - `profile` - `profile-version` - `guide-version` - `applies-to` - `canonical-url` - `repository-url` - `last-reviewed` The verifier SHOULD check optional fields when present: - `source-path` - `reviewed-by` - `status` - `superseded-by` - `preferred-languages` - `valid-until` - `recommended-verifier` - `verifier-conformance` - `registry-url` - `manifest-url` The verifier MUST validate URL fields as ASCII URLs with ASCII hostnames. Internationalized domain names MUST be expressed in punycode A-label form. The verifier MUST warn when a non-URL metadata value exceeds 80 bytes. URL-valued fields are exempt because a legitimate canonical or repository URL can be long; all other field values are short by design, and an unusually long one is a side-channel risk per guide-profile section 27. The verifier SHOULD warn when `canonical-url`, `repository-url`, `registry-url`, `manifest-url`, or `recommended-verifier` use unrelated registered domains without explanation. The verifier SHOULD warn when `recommended-verifier` is not on the same registered domain as `canonical-url`, unless the guide explicitly identifies it as third-party or the URL matches the standard primary verifier for the applicable verifier-profile version. The reference verifier emits `metadata.recommended-verifier.off-domain` for an off-domain `recommended-verifier` unless it is the configured standard primary verifier for the applicable profile version. The verifier MUST NOT warn solely because `recommended-verifier` differs from `canonical-url` when `recommended-verifier` matches the standard primary verifier configured for the applicable profile version. When package-registry metadata is used as an independent Level 4 anchor, the verifier MUST require `registry-url` and MUST validate that it identifies a specific registry record rather than a registry homepage or search result. When `registry-url` is absent and no other Level 4 independent anchor is available, the verifier SHOULD emit an informational finding for Level 3 and a blocking finding for Level 4. ## 15. Verification Instruction Checks For Level 1 and above, the verifier MUST check that a compact verification instruction appears before action instructions. The verifier MUST check that the instruction includes these concepts: - verify the guide with a recommended verifier or another conformant verifier - report achieved level, guide SHA-256, and blocking findings - obtain user confirmation before actions - do not execute actions before confirmation The verifier SHOULD warn when a guide names a recommended verifier but omits `verifier-conformance` metadata. The verifier MUST emit an error when a guide states or implies that only one verifier is authoritative. The verifier SHOULD check whether DNS TXT or signed `security.txt` fields identify a recommended verifier. When those anchors disagree with `recommended-verifier`, the verifier SHOULD emit a warning unless one value is the configured standard primary verifier and the other is explicitly marked as a publisher-local verifier. ## 16. Required Section Checks For Level 3 and above, the verifier MUST check for the required guide sections or equivalent clearly identifiable content: - title - canonical source URL - publisher or repository URL - guide metadata - task scope - assistant invocation prompt - safety rules - action classification - normal commands or action classes - stop-and-ask conditions - acceptance checklist - threat model - untrusted content handling - disclaimer and non-goals - authority model Section names may vary. The verifier MAY use heading matching, key phrase matching, or structured markers. When using approximate matching, the verifier SHOULD report confidence or evidence snippets. ## 17. Action Block Parsing The verifier MUST parse action blocks by exact fence match: ```text [action] ... [/action] ``` Fence markers are case-sensitive and MUST carry no leading or trailing whitespace. A line that equals a fence marker only after trimming surrounding whitespace or folding letter case (for example `[ACTION]` or `[action] `) MUST NOT open or close a block and MUST raise a blocking finding (`action-block.malformed` for action fences, `metadata.malformed`/`metadata.block-count` for the metadata fence). The verifier MUST NOT silently treat a near-miss marker as body text: a whitespace- or case-lenient agent parser may honor a marker the verifier ignores, and that divergence is exactly the review-integrity gap this profile exists to close. The metadata-block presence test MUST likewise be case-insensitive so an upper- or mixed-case metadata fence is parsed and flagged rather than skipped. For Level 3 and above, every substantive action MUST be represented by an action block. Each action block MUST include: - `id` - `class` - `approval` - `command` Each action block MAY include: - `runner` - `cwd` - `env` - `egress` - `notes` The verifier MUST reject action blocks with: - duplicate `id` values - missing required fields - malformed `key: value` lines - nested action fences - unknown `approval` values - invalid `runner` values - values outside the byte profile The verifier MUST parse `class` as a comma-separated list. The `normal` class is mutually exclusive with all other classes. Allowed classes are: - `normal` - `networked` - `destructive` - `privileged` - `persistence-changing` - `data-accessing` - `code-executing` ## 18. Action Approval Checks The verifier MUST emit an error when an action whose class list includes any of the following has `approval: not-required`: - `privileged` - `destructive` - `persistence-changing` - `data-accessing` - `code-executing` For Level 4, the verifier SHOULD warn when actions whose class list includes `networked` do not use `approval: required`. For Level 5 readiness, the verifier SHOULD warn unless all `networked`, `privileged`, `destructive`, `persistence-changing`, `data-accessing`, and `code-executing` actions use `approval: required`. The verifier SHOULD count required approvals and warn when the total exceeds a default threshold of 10. ## 19. Command Field Checks The verifier MUST check every `command` field for guide-profile command restrictions: - one command per action block - no chaining with `&&`, `||`, `;`, or newline - no shell substitution using `$(`, backticks, or `${` - no redirection or pipes unless the action is only classed as `normal` and the redirection target is inside declared `cwd` - no glob expansion in actions classed as `destructive` or `privileged` - environment-variable references via `$NAME` only when the variable is listed in `env` The verifier SHOULD warn on commands likely to execute project code, dependency code, package scripts, build hooks, generated code, test suites, or local scripts unless the action includes `code-executing`. Examples include: - package manager install commands with lifecycle scripts - test runners - build tools - local shell scripts - Python, Ruby, Node, or other interpreter invocations over local files - `make`, `just`, `task`, or similar task runners ### Command and class consistency The verifier SHOULD cross-check each command against its declared `class` by analysing the COMMAND HEAD of each pipeline segment (the invoked program, after stripping a leading path, a trailing version suffix, leading `VAR=value` assignments, and pure prefixes such as `sudo`, `env`, or `exec`). The verifier MUST NOT infer a capability from a bare word appearing anywhere in the command, because a tool name frequently appears as an argument (for example `apt-get install curl` installs a package; it does not perform `curl` egress). - When a segment head is a network client and the action does not declare `networked`, the verifier SHOULD warn (`network.command-implies-networked`). - When a segment head is an interpreter fed code (an inline-code flag, a script-file argument, an inline program argument, or any program reading from a pipe) or a package or build tool, and the action does not declare `code-executing`, the verifier SHOULD warn (`action-block.class.code-executing-missing`). - When a command implies a sensitive capability but the action neither declares an approval-requiring class nor sets `approval: required`, the verifier SHOULD warn (`approval.command-implies-required`). - When a command pipes a network fetch directly into an interpreter (the remote-code-execution shape, for example `curl URL | sh`), the verifier MUST raise a blocking finding (`command.fetch-execute`). Authors who must fetch and then run content SHOULD express the fetch and the execution as two separate, individually approved actions. These command-content checks are heuristic and cannot decide arbitrary shell semantics; apart from the unambiguous fetch-execute shape they are advisory warnings, and human review remains required. A verifier MUST NOT treat the absence of a command-content warning as evidence that a command is safe. The verifier SHOULD warn when `runner: shell` is present without a narrow rationale in `notes`. The verifier SHOULD warn when Level 4 guides omit `runner`. ### Bounded execution checks (2.0.0) For guide-profile 2.0.0, the verifier evaluates whether a `code-executing` action keeps the executed instructions inside the reviewed guide (spec section 12, "Code-executing actions and the review boundary"). Classification is by tokenized invocation shape, not program name: - Bound: the command syntax identifies a publisher-controlled repository artifact or dispatch file (a `./`-prefixed or absolute-path script, an interpreter with a local script-file argument, `make `, `npm run