docs: publish schema reference for spark-compete-hotfix-v1 (pr.body_must_include, evidence_types enum)

[rifki0908]

Spark Compete packet validator: missing schema reference for pr.body_must_include and review_claim.evidence_types

Schema: spark-compete-hotfix-v1
Validator endpoint: https://compete.sparkswarm.ai/api/packet/validate

Problem

When trying to satisfy the spark-compete-hotfix-v1 packet schema, two fields produce schema_const / schema_enum errors with no discoverable allowed values:

1. pr.body_must_include — every value tested (field names, schema names, header strings) returns schema_const: Field does not match the required schema value for index 0, plus schema_contains: Array is missing a required schema value.
2. review_claim.evidence_types — limited probing surfaced only two valid enum values (smoke_test, public_api_response); the full enum is unknown.

What we already tried

• Probed /api/packet/schema, /api/packet/help, /api/packet/options, /api/packet/example, /api/packet/template, /schema/spark-compete-hotfix-v1.json — all return {"error":"not_found"}.
• Inspected packet bodies of merged/passed PRs (fix(security): add standard localhost hostname variants to LOCAL_HOSTS #101, fix: show guidance when spark list finds no modules #146, feat: add missing spark-skill-manifest.v1.schema.json #199, fix: spark fix spawner/providers/memory/live/update --json missing top-level ok field #285) — older format does not include submission_mode, submission_target_url, pr.body_must_include, pr.title_prefix, etc., suggesting the schema was tightened after those merged.
• Tested body_must_include with single-element arrays containing field names from the packet itself (team, target_repo, submission_mode, etc.), the schema name (spark-compete-hotfix-v1), the event ID, header strings, and packet path expressions — all rejected with schema_const.
• Repeated probing across array lengths 0/1/2/8 — same schema_const error pattern; no partial-match feedback.

Request

Please publish one of:

• The JSON Schema document for spark-compete-hotfix-v1 (e.g. at /api/packet/schema or in this repo).
• A documented example of a fully-valid 2026-05-23+ packet (current best example is from PR feat: add missing spark-skill-manifest.v1.schema.json #199 / fix: spark fix spawner/providers/memory/live/update --json missing top-level ok field #285, which now fails the new validator).
• An enum list for pr.body_must_include and review_claim.evidence_types.

Why this matters

Twelve [spark-compete] fix(security): ... PRs across spark-cli, vibeship-spawner-ui, spark-telegram-bot, and spark-domain-chip-labs are blocked by needs-valid-packet even after every other validator error has been resolved (errors went from 20 → 3, all remaining are body_must_include schema_const). Without published schema reference, contributors are guessing at validator-internal constants.

Public-safe context

• No private logs, secrets, or admin-state were inspected.
• No private dashboards or maintainer-only routes were probed.
• Validator API rate-limit is respected (one request batch hit 429: too_many_packet_validation_attempts, then waited 5min before retrying).

Filed under the Spark Compete public-packet policy spark-compete-public-packet-policy-v1. Treating this as a tooling/docs gap rather than a code bug.

Thanks!