docs: restore truth-gate invariants to unblock queue-wide test CI failure

[groupthinking]

Summary

The required test CI job is failing on every open PR in the queue on a single assertion — 7424 passed, 1 failed:

tests/unit/test_agent_completion_gate.py::CompletionGateDocumentationTests::test_operator_doc_defines_schemas_and_enforcement
AssertionError: 'Snapshot creation is label-event-only' not found in docs/agent-completion-truth-gate.md

Root cause (git-archaeology, not guesswork): commit 0b65565 ("fix(ci): bind truth-gate snapshots and evidence") changed the workflow, the test, and the operator doc together — introducing label-event-only snapshots, GITHUB_TOKEN markers that don't recursively trigger issue_comment, and resolve/collection/publication-time base+head SHA equality (stale_base/stale_head). A later docs-only commit 21d94b5 rewrote the file and reverted those two paragraphs to their pre-0b65565 wording, dropping four phrases the test still asserts:

• Snapshot creation is label-event-only
• does not recursively trigger \issue_comment``
• Resolve-time, collection-time, and publication-time PR base and head
• immutable resolved base/head commit comparison

The behaviours are still implemented in .github/workflows/pr-checks.yml (the snapshot-agent-task-intent job, RESOLVED_BASE_SHA/RESOLVED_HEAD_SHA, stale_base/stale_head), so this restores the accurate description rather than weakening the test to match a stale doc. Documentation-only change (+2 / -2 lines).

Linked issue

Fixes #

Verification

• Focused tests — python -m unittest tests.unit.test_agent_completion_gate.CompletionGateDocumentationTests → 3 tests OK (the previously-failing case now passes)
• Required CI — test job expected green with this change; build job remains red for an unrelated, upstream reason (see below)
• Review threads resolved

Separately observed queue-wide blockers (NOT addressed here)

These affect the whole open-PR queue and are out of scope for this doc fix:

1. build job — ESLint crash, upstream ecosystem gap. eslint src middleware.ts dies with TypeError: Cannot read properties of undefined (reading 'Cjs') at @typescript-eslint/typescript-estree/dist/create-program/shared.js:59 (ts.Extension.Cjs). The repo is on typescript@6.0.3, whose runtime no longer exposes the Extension enum (the type survives in .d.ts; the runtime value does not). Every published @typescript-eslint 8.x — including the newest, 8.64.0 — still references ts.Extension.* at runtime, so no version bump fixes this, and build(deps-dev): bump typescript from 6.0.3 to 7.0.2 #882 deliberately kept the repo on TS 6 (it reverted the bump to 7). A real resolution needs an upstream typescript-eslint release with TS 6/7 support, or a scoped decision to change the TS/lint toolchain — not a change I could verify in this session, so I did not ship a guess.
2. CodeRabbit is non-functional across the queue — "Prepaid credits exhausted" / "Review skipped: excluded by label configuration".
3. The advisory agent-completion/truth-gate/pr-* status is red queue-wide (publication/invalid_payload), and Vercel preview deploys are failing — both external/config, not code.

Agent provenance

Authored by a Claude Code agent session (model claude-opus-4-8[1m]). No trusted-publisher identity is provisioned in .github/agent-lock/trusted-publishers.json, so no machine-readable agent-lock-manifest / agent-lock-event is asserted — this is a human-readable provenance note rather than forged enforcement evidence. Please review before merge.

---

🤖 Generated with Claude Code

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
v0-uvai	Ready	Preview, Comment, Open in v0	Jul 19, 2026 3:25pm

[coderabbitai]

Important

Review skipped

Auto reviews are limited based on label configuration.

🏷️ Required labels (at least one) (1)

• [‘architecture-gap’, ‘bug’, ‘ci-cd’, ‘ci/cd’, ‘copilot-rabbit’, ‘documentation’, ‘duplicate’, ‘enhancement’, ‘frontend’, ‘github_actions’, ‘good first issue’, ‘help wanted’, ‘high-priority’, ‘invalid’, ‘javascript’, ‘ml-model’, ‘needs-triage’, ‘pipeline-critical’, ‘placeholder-code’, ‘priority:high’, ‘python’, ‘python:uv’, ‘question’, ‘styling’, ‘tests’, ‘v0’]

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository YAML (base), Repository UI (inherited), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Pro

Run ID: 7249c978-4d36-480d-852b-a15a5c5c3f17

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch claude/determined-maxwell-3o6tqe

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch claude/determined-maxwell-3o6tqe

---

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Snapshot Warnings

⚠️: No snapshots were found for the head SHA bc7d67e.

Ensure that dependencies are being submitted on PR branches and consider enabling retry-on-snapshot-warnings. See the documentation for more information and troubleshooting advice.

Scanned Files

None

[github-actions]

Agent Completion Truth Gate: BLOCKED

Reasons: invalid_payload

Machine-readable verdict

{
  "details": {
    "invalid_fields": [
      "issue.number",
      "policy.agent_login",
      "policy.run_id"
    ]
  },
  "reasons": [
    "invalid_payload"
  ],
  "verdict": "blocked"
}

Workflow evidence

[Copilot]

Pull request overview

Restores truth-gate documentation to match its existing workflow invariants and documentation tests.

Changes:

• Documents label-only intent snapshots and GITHUB_TOKEN behavior.
• Documents base/head SHA consistency and immutable commit comparison.