feat(ci): Implement cross-repo-validate compliance for docs sync

Summary

The cross-repo-validate action in aRustyDev/docs has been updated with new requirements for sync PRs. This issue tracks the changes needed in mdbook-htmx's cross-repo-sync workflow to comply with validation.

Current State vs Required State

1. Branch Pattern

Aspect	Current	Required
Format	docs-sync/<repo>/<sha>	docs-sync/<source-repo>
SHA location	In branch name	In manifest only
Purpose	Unique per commit	Stable for CI reruns

Why: Stable branch pattern allows re-running CI without creating duplicate PRs.

2. Manifest Location

Aspect	Current	Required
Location	PR diff (file in commit)	PR body (between markers)
Format	JSON file	JSON in HTML comments

Required PR body format:

<!-- BEGIN_SYNC_MANIFEST -->
{
  "$schema": "https://schemas.arusty.dev/cross-repo-sync/manifest/v1",
  "version": "1.0",
  "source": { ... },
  "target": { ... },
  "sync": { ... },
  "files": [ ... ],
  "checks": [ ... ]
}
<!-- END_SYNC_MANIFEST -->

<!-- ROOT_ATTESTATION_ID: <attestation-id> -->

3. Manifest Schema

The manifest must include:

{
  "$schema": "https://schemas.arusty.dev/cross-repo-sync/manifest/v1",
  "version": "1.0",
  "source": {
    "repository": "aRustyDev/mdbook-htmx",
    "sha": "<40-char-sha>",
    "ref": "refs/heads/main",
    "workflow_run_id": "<run-id>"
  },
  "target": {
    "repository": "aRustyDev/docs",
    "branch": "docs-sync/mdbook-htmx",
    "path_prefix": "library/gh/mdbook-htmx"
  },
  "sync": {
    "type": "docs",
    "id": "<uuid>",
    "timestamp": "<ISO-8601>"
  },
  "files": [
    {
      "path": "library/gh/mdbook-htmx/README.md",
      "sha256": "<64-char-hash>"
    }
  ],
  "checks": [
    {
      "name": "lint",
      "id": "<uuid>",
      "result": "passed",
      "attestation": {
        "id": "<attestation-id>"
      },
      "timestamp": "<ISO-8601>"
    }
  ]
}

4. Attestation Architecture

Component	Required Action
Check attestations	For each check, use gh attestation attest on check result JSON
Root attestation	Use gh attestation attest on final manifest
PR body	Include root attestation ID as HTML comment

Flow:

1. For each check (lint, build, etc.):
   • Run check
   • Output result to JSON
   • gh attestation attest <check-result.json>
   • Add attestation ID to manifest's checks[].attestation.id
2. When all checks complete:
   • gh attestation attest <manifest.json>
   • Include manifest + root attestation ID in PR body

5. Labels

Aspect	Required
Label	docs-sync (matches <sync-type>-sync pattern)
Timing	Applied when PR is created

Implementation Checklist

• Update branch naming to stable pattern (docs-sync/mdbook-htmx)
• Generate manifest with required schema fields
• Implement check attestations (for each check step)
• Implement root attestation on manifest
• Embed manifest in PR body between markers
• Include root attestation ID as HTML comment
• Apply docs-sync label to PR
• Compute SHA256 hashes for all synced files

Reference

• cross-repo-validate action
• Manifest schema
• Validation workflow

Priority

High - sync PRs will fail validation until this is implemented.