feat(agent): add Contract Validator GitHub Action and agent contract (#33)

[ghzhost]

Overview

Closes #33.

Implements the Contract Validator GitHub Action as the first live governed agent running directly in this repository.

Key Deliverables:

1. .github/agents/contract-validator/contract.yaml:

   • Conforms strictly to Agent Contract Specification v1.1.
   • Read-only agent permissions (github:pull-requests:read, github:pull-requests:write).
   • Declares side effects (PR feedback comment only, non-destructive/reversible).
   • Approval points: None (read-only advisory reporting).
   • Lifecycle: request-response, stateless.

2. .github/agents/contract-validator/README.md:

   • Documents agent scope, governance specification, and local testing instructions.

3. .github/workflows/validate-contracts.yml:

   • Added validate-pr-contracts job that triggers on PRs, detects modified .yaml files, validates them with scyvera.validate_contract(), and posts/updates an advisory feedback comment on the PR.
   • Non-blocking execution pattern per issue requirements (emits GitHub Actions warning/advisory if violations exist, leaving merge decision to maintainers).

4. scripts/validate_pr_contracts.py & tests/test_pr_validator.py:

   • CLI script and unit test suite verifying validation logic and governance report markdown output.

Validation:

• Ran full test suite via pytest -v (62/62 tests passing).
• Verified scyvera validate .github/agents/contract-validator/contract.yaml and scyvera lint.

[Skull-boy]

Hey @ghzhost — good work overall, the structure is clean.
One failing check to fix before we merge.

Root cause

Fork PRs trigger with a read-only GITHUB_TOKEN by default —
GitHub blocks write operations (like posting comments) from fork
contexts for security reasons. The 403 you're seeing is that restriction.

Fix — split into two workflows

The clean pattern for this is separating validation from commenting:

1. Workflow 1 (validate-contracts.yml) — triggers on pull_request,
   runs validation, saves the report as an artifact. Read-only,
   always works on forks.

2. Workflow 2 (post-validation-comment.yml) — triggers on
   workflow_run (when Workflow 1 completes), downloads the artifact,
   posts the comment. Runs in repo context so it has write permission.

# post-validation-comment.yml
on:
  workflow_run:
    workflows: ["Validate Agent Contracts"]
    types: [completed]

permissions:
  pull-requests: write

jobs:
  comment:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/download-artifact@v4
        with:
          name: pr-report
          github-token: ${{ secrets.GITHUB_TOKEN }}
          run-id: ${{ github.event.workflow_run.id }}
      - uses: actions/github-script@v7
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          script: |
            const fs = require('fs');
            const body = fs.readFileSync('pr_report.md', 'utf8');
            const pr = ${{ github.event.workflow_run.pull_requests[0].number }};
            await github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: pr,
              body
            });

Separate issue — contract.yml naming

The validator itself flagged .github/workflows/validate-contracts.yml
as using contract.yml instead of contract.yaml. Rename that file
to comply with the spec. Good proof the agent works — it caught
its own contributor's naming error.

62/62 tests passing is great. Once the workflow split is done this
is ready to merge.