Skip to content

validation-rules.md

Latest commit

 

History

History
176 lines (109 loc) · 7.38 KB

validation-rules.md

File metadata and controls

176 lines (109 loc) · 7.38 KB
Raw

Validation rules

Automated checks that run on every pull request touching agents/ or starter-kits/. Each rule reports with its ID, so a failure comment points straight at the section below.

Two escape hatches exist, and neither is a way to skip review:

  • Waivers (.github/policy/waivers.yaml) — a reviewed exception for one rule on one path. Requires a CODEOWNER approver and an expiry date; an expired waiver fails the build.
  • Ratchet baseline (.github/policy/baseline.json) — violations that predate a rule. Reported as warnings so legacy content keeps building, while any new violation of the same rule still blocks.

Rule index

Rule Summary Applies to Severity
POL-008 Files under agents/ and starter-kits/ must be source code or POL-016-compliant Markdown images, verified by content inspection. Every changed file error
POL-014 Dockerfile base images must be Docker Official Images or come from an approved registry or publisher namespace. Every changed file error
POL-015 Added files must use an approved extension or filename from the source allowlist. Every changed file error
POL-016 Images under agents/ or starter-kits/ must be safe Markdown formats, at most 1 MiB, and referenced by Markdown in the same catalog item. Every changed file error
POL-017 Base image tags should be pinned to an explicit version rather than a floating tag such as :latest. Every changed file warning
POL-018 Catalog webpage URLs must resolve to reachable public HTML pages. Whole repository warning
POL-019 Catalog contact email domains must exist and advertise usable mail DNS records. Whole repository error
POL-020 UTF-8 source text must not contain unsafe or invisible Unicode characters. Every changed file error
TAG-001 Tags declared in metadata.yaml must exist in the controlled tag vocabulary. Each touched agent folder error
TAG-002 Authors must not declare tags in the CI-computed namespaces (auto:, tier:, party:, capability:). Each touched agent folder error

POL-008

Files under agents/ and starter-kits/ must be source code or POL-016-compliant Markdown images, verified by content inspection.

  • Applies to: Every changed file
  • Severity: error
  • Tags: security, supply-chain

How to fix

Remove the binary from the PR. Compile or download it inside the tool's Dockerfile, or host it externally and reference it by URL. Small Markdown images are permitted under POL-016; model weights must satisfy POL-009.

Further reading: docs/authoring-guides/agent-authoring-guide.md#no-binaries

POL-014

Dockerfile base images must be Docker Official Images or come from an approved registry or publisher namespace.

  • Applies to: Every changed file
  • Severity: error
  • Tags: security, supply-chain

How to fix

Switch the FROM line to a Docker Official Image, an mcr.microsoft.com image, or an approved publisher namespace from .github/policy/base-images.yaml.

Further reading: docs/authoring-guides/agent-authoring-guide.md#base-images

POL-015

Added files must use an approved extension or filename from the source allowlist.

  • Applies to: Every changed file
  • Severity: error
  • Tags: hygiene

How to fix

Rename the file to an approved type, remove it, or extend .github/policy/source-allowlist.yaml in a separate CODEOWNERS-reviewed PR.

Further reading: docs/authoring-guides/agent-authoring-guide.md#approved-file-types

POL-016

Images under agents/ or starter-kits/ must be safe Markdown formats, at most 1 MiB, and referenced by Markdown in the same catalog item.

  • Applies to: Every changed file
  • Severity: error
  • Tags: security, integrity

How to fix

Use PNG, JPEG, GIF, WebP, or SVG; keep the file at or below 1 MiB; and embed it from Markdown in the same agent or starter-kit folder. Re-export the image if its content does not match its extension. For SVG, remove scripts, event handler attributes, javascript: URIs, entity declarations, embedded documents, and remote references — the catalog accepts declarative artwork only.

Further reading: docs/authoring-guides/agent-authoring-guide.md#images

POL-017

Base image tags should be pinned to an explicit version rather than a floating tag such as :latest.

  • Applies to: Every changed file
  • Severity: warning
  • Tags: supply-chain, reproducibility

How to fix

Replace the floating tag with an explicit version, or supply it through an ARG with a pinned default so the version is a visible build input.

Further reading: docs/authoring-guides/agent-authoring-guide.md#base-images

POL-018

Catalog webpage URLs must resolve to reachable public HTML pages.

  • Applies to: Whole repository
  • Severity: warning
  • Tags: network, publisher, ssrf

How to fix

Use an HTTPS URL on port 443 that resolves only to public addresses, follows at most five public HTTPS redirects, and returns a non-empty HTML or XHTML response with a successful HTTP status. This check validates reachability only; it does not prove the page belongs to the named publisher.

Further reading: docs/authoring-guides/agent-authoring-guide.md#metadata-reference

POL-019

Catalog contact email domains must exist and advertise usable mail DNS records.

  • Applies to: Whole repository
  • Severity: error
  • Tags: network, publisher, email

How to fix

Use an address whose fully qualified domain publishes a non-null MX record, or an A/AAAA record permitted by implicit-MX fallback. This check validates the domain only; it does not prove mailbox ownership.

Further reading: docs/authoring-guides/agent-authoring-guide.md#metadata-reference

POL-020

UTF-8 source text must not contain unsafe or invisible Unicode characters.

  • Applies to: Every changed file
  • Severity: error
  • Tags: security, integrity, unicode

How to fix

Save the file as valid UTF-8 and remove the reported control, bidirectional, zero-width, private-use, unassigned, noncharacter, replacement, or non-standard separator code point. Normal visible international and scientific text is allowed.

TAG-001

Tags declared in metadata.yaml must exist in the controlled tag vocabulary.

  • Applies to: Each touched agent folder
  • Severity: error
  • Tags: discoverability

How to fix

Use an existing tag from .github/policy/tag-taxonomy.yaml, or propose the new tag in a separate PR against that file.

Further reading: docs/authoring-guides/agent-authoring-guide.md#tags

TAG-002

Authors must not declare tags in the CI-computed namespaces (auto:, tier:, party:, capability:).

  • Applies to: Each touched agent folder
  • Severity: error
  • Tags: integrity, discoverability

How to fix

Remove the reserved-prefix tag from metadata.yaml. CI applies these automatically based on the agent's contents.

Further reading: docs/authoring-guides/agent-authoring-guide.md#tags

Other validation families

The REL-*, STR-*, SCH-*, DOC-*, and remaining POL-* checks live in .github/scripts/catalog_validation/. They run alongside this modular engine from the shared PR validation runner. See docs/validation-rules.csv for the complete source-backed inventory.