fix(ci): preserve browser evidence and pin source freshness

[BunsDev]

Scope

Refs #89; closes no issue. Repair the documentation E2E/CI evidence path without weakening source freshness or publication acceptance.

Base: e0860cd68030248fb829b00bc32d684fd1720ff2
Head: 44f10e33604c2abfb659baca965006a0c2e545f7

Observed failures

• Docs run 34664876044, job 103474663562, installed dependencies successfully, then failed source freshness. Chrome installation and pnpm verify were skipped. That run does not establish a browser regression in dependency PR chore(deps): bump the next-react group across 1 directory with 2 updates #90.
• Scheduled drift run 34770362387 detected four watched paths and deliberately failed the final gate. docs-stale: upstream contract sources changed #89's outstanding source-to-page review remains necessary.
• The existing detector used verifiedAt as a commit-history filter and repeatedly queried moving main. A late-merged old-dated change can evade that timestamp filter; separate reads can mix revisions. comparison.head_commit also does not reliably establish the target identity.

Changes

1. Run source freshness and complete browser/build verification as independent jobs. Preserve the canonical Verify documentation release check as an always-running rollup requiring both jobs to return literal success. Missing, failed, cancelled, skipped, or pending outcomes fail. No continue-on-error, weakened assertion, new quarantine, or release waiver.
2. Resolve the upstream ref once; prove reviewed-commit ancestry against the exact target; compare watched path identities in pinned non-recursive Git trees. Preserve mode/type/blob/tree identity, additions/deletions and ancestor symlink obstructions. Refuse truncated/malformed trees, incomplete identity, missing-both watches and API errors. Do not rely on date-filtered history or the comparison endpoint's capped file list.
3. Retain exact snapshot evidence and separate freshness/browser artifacts. Document that changes now represents current path-identity differences, not exhaustive historical chronology. A reverted path with exactly the reviewed identity is unchanged for current docs purposes; this does not certify deployed behavior or historical events.
4. Add 83 dependency-free CLI/workflow regression tests and wire them into both CI and existing check:automation / pnpm verify.

Exactly seven changed files. No dependency manifests, source-lock values, public product claims, runtime behavior, branch protections, deployment controls, or release credentials changed.

Verification actually executed

• Reconstructed the unchanged baseline detector and verified its Git blob is exactly c224c745753472c82ea2893b511999c95f3db86d.
• Ran the same selected fixture CLI regressions against that baseline: 7 failures, demonstrating false clean results for late-merged old-dated changes, moving-ref evidence, additions/deletions, mode changes, and empty lock.
• node --test scripts/check-source-drift.test.mjs scripts/docs-release-gate.test.mjs: 83 passed, 0 failed, 0 skipped/cancelled on Node 22.16.0.
• node --check for all changed/new JavaScript modules: passed.
• Parsed workflow YAML and verified independent jobs, exact dependency rollup, and no continue-on-error: passed.
• Whitespace/newline checks and local Git blob manifest: passed.

These are real subprocess executions against fixture-controlled GitHub responses, not live upstream verification. The 83 cases comprise 33 source-drift cases, all 49 pairings of seven gate outcomes, and one workflow wiring contract.

Remaining gates and review

Full frozen install, pnpm verify, Chrome/browser certification and live GitHub drift detection have not run in this sandbox; package/network access is unavailable. Inspect exact-head CI before claiming those outcomes. Source freshness is expected to stay red until #89's substantive review is completed.

Do not merge by bypassing the canonical gate. Review the workflow topology and the shift from timestamp-history to current pinned-tree semantics. Then complete the separately scoped source-to-page review and truthful verifiedCommit / verifiedAt update; this PR does not supply or fabricate that review.

This is an API-authored scoped review branch under Val's instruction to patch E2E blockers. It does not modify any existing agent worktree or claim a canonical Bead registration, host census, release, or deployment. Existing operational/security gates remain open.

[vercel]

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

Project	Deployment	Actions	Updated
coven-docs	Ready	Preview	Sep 14, 2026 6:36am UTC

[BunsDev]

Exact-head hosted verification receipt

Run 34814168620 exercised head 44f10e33604c2abfb659baca965006a0c2e545f7 through merge tree bbb74861642c13c562dd9e5a198a3f823860efc6 against base e0860cd68030248fb829b00bc32d684fd1720ff2.

• Browser/build job 103881261316: completed/success. Frozen install, Chrome installation, complete pnpm verify, clean-generated-tree check and evidence upload all succeeded.
• 83 automation regressions: passed in hosted CI, zero failures/skips/cancellations, as well as locally.
• Freshness job 103881261446: completed/failure for four actual watched-path differences, not a malformed API response or detector crash.
• Canonical Verify documentation release job 103881552640: completed/failure, correctly rejecting the combination of browser success and freshness failure. No bypass or merge performed.

Downloaded and independently checked both artifact ZIP SHA-256 digests:

1. docs-certification-34814168620, artifact 10336057214, digest fdbb539361d9996e379fda7446d7132dda21b022ba4727ca477a2717d1d3ced9. Its report binds the merge tree above, returns ok:true, and records 12 HTTP-200 routes with canonical/H1/main checks, four journey categories, three 390px mobile overflow checks, and five screenshots. This is the CI-built localhost site, not production deployment evidence.
2. docs-source-drift-34814168620, artifact 10336191598, digest d54d84e78e30b8b34e2e50768a4f1323d05b86da516432431a19b42b9b530642. It records verificationMode: git-tree-identity, exact upstream target a566c26d2bf725a0dee6b4c290fe8718ab52375b, and differences in crates/coven-cli/src/main.rs, crates/coven-cli/src/api.rs, crates/coven-cli/src/setup/process.rs, and docs/API-CONTRACT.md; all eight other watched identities match the reviewed snapshot.

This supersedes the initial PR body's pending hosted-verification status, not its source-review limit. The topology repair now has real browser execution evidence and real fail-closed rollup evidence. #89 still needs substantive review of those four source paths against affected public pages, followed by a truthful lock update and fresh successful canonical CI. Do not merge this PR by ignoring that remaining gate.

[Copilot]

🔵 Needs a closer look

Full frozen-install, browser, and live drift gates were not run in this sandbox.

Pull request overview

This PR repairs documentation CI evidence and source-freshness detection while preserving a strict release gate.

Changes:

• Separates freshness and browser verification jobs.
• Pins drift checks to immutable Git tree identities.
• Adds regression coverage and documents evidence semantics.

File summaries

File	Summary
scripts/docs-release-gate.test.mjs	Tests release-gate outcomes and workflow wiring.
scripts/docs-release-gate.mjs	Requires both verification jobs to succeed.
scripts/check-source-drift.test.mjs	Adds source-drift regression coverage.
scripts/check-source-drift.mjs	Implements pinned, fail-closed tree comparison.
scripts/check-automation-syntax.mjs	Runs automation regression tests.
docs/e2e-source-freshness.md	Documents evidence and freshness semantics.
.github/workflows/docs.yml	Adds independent verification jobs and canonical rollup.

Review details

• Files reviewed: 7/7 changed files
• Comments generated: 0
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.