fix(metadata): preserve workflow-backed GitHub Pages

[seonghobae]

Outcome

Repair the central repository metadata reconciler so a repository with an explicitly reviewed Actions-backed GitHub Pages deployment is never rewritten to legacy /docs publishing.

• add optional pages_mode: workflow desired-state intent while preserving the existing legacy default;
• require the standard reviewed .github/workflows/pages.yml source contract for workflow mode instead of docs/index.md;
• fail closed if workflow mode is requested but Pages is missing or the live configuration is not build_type: workflow;
• validate workflow-mode live Pages state before description/topic/Page mutation so a failed record cannot be partially applied;
• treat a Contents API source as valid only when it is a single type: file object, rejecting directory objects/listings;
• preserve an existing Actions-backed Pages configuration without POST/PUT/DELETE mutation;
• keep live status, organization-owned Pages URL, and non-empty publication verification authoritative;
• include the workflow-mode test module in both pull-request path filtering and the 100% metadata coverage gate;
• retire superseded PR validation runs while deliberately preserving the protected-main hourly reconciliation apply;
• update ADR-0020, the operational doctoring baseline, and ARCHITECTURE.md with the mode-aware ownership and fail-before-write contract.

Test-first/root-cause remediation

The first workflow-mode implementation exposed measured compatibility and branch-coverage gaps. Those were repaired rather than hidden: established legacy error wording was preserved and direct regressions were added for the workflow source probe, missing-workflow apply rejection, and missing-workflow verification rejection.

A later Devin review identified two substantive defects on the then-current head. First, missing/legacy workflow Pages was rejected only after description/topic writes. Second, the generalized source probe accepted a directory/listing as file evidence. The canonical branch received RED regressions first (test_workflow_pages_reconcile_fails_closed_before_any_metadata_write and test_repository_file_probe_requires_a_regular_file), then production was changed so the workflow live-state precondition runs before every metadata write and only a plain Contents object with type: file satisfies the source contract. Devin subsequently marked both findings resolved.

The same investigation exposed an Actions-capacity defect: PR validation already used a PR-stable github.ref concurrency group but did not cancel predecessors. The workflow now keeps the established group and uses cancel-in-progress: ${{ github.event_name == 'pull_request' }}. Live predecessor run 33542147515 became terminal cancelled when a replacement head arrived, while scheduled protected-main apply remains non-cancellable.

Current exact identity

• protected base: main@09090e98ca6fe34ee0ab8a0a8145d7af0a0bb9aa;
• exact head: 78a0791339147e18afcc443ebe88213cfa83184b;
• branch is mechanically mergeable against current main;
• the current head is a normal two-parent, non-force reconciliation of the prior fix(metadata): preserve workflow-backed GitHub Pages #1628 lineage with protected main, preserving hardening(urllib): make redirect rejection explicit #1631's explicit urllib HTTPError hardening and docs(sentinel): remove false urllib SSRF record #1633's corrected removal of the false Sentinel SSRF record;
• all substantive Devin findings are resolved; the only remaining unresolved thread is an outdated informational note about the already-correct redirect regression;
• fresh exact-head workflows are regenerating under a repository Actions queue above 880 runs. Predecessor results are historical and do not authorize this head.

Safety boundary

This does not enroll ScopeWeave or another repository by itself, change a live Pages setting, weaken legacy /docs verification, bypass branch protection, or claim publication. Existing boolean-only manifest records continue to mean legacy /docs Pages. A workflow-backed repository must opt in explicitly through reviewed desired state after this capability is integrated. Scheduled protected-main reconciliation stays non-cancellable so a later heartbeat cannot abandon a partially updated fleet.

Coordination

This is the owner-side repair for #1627 and is intentionally independent of #1622 (manifest expansion), #1625 (dedicated settings credential), and #1626 (manual reconciliation dispatch). A later workflow-backed canary must preserve its current Actions deployment and verify live publication after protected integration.

Closes #1627 only after protected integration and a workflow-backed canary reconciliation prove the live deployment is preserved.

[coderabbitai]

Warning

Review limit reached

Next included review available in 48 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: 53c9adb8-fb52-45ff-8308-dccc5dd96052

📥 Commits

Reviewing files that changed from the base of the PR and between 09090e9 and 78a0791.

📒 Files selected for processing (6)

• .github/workflows/repository-metadata-reconcile.yml
• ARCHITECTURE.md
• docs/adr/0020-repository-public-surface-reconciliation.md
• docs/doctoring/repository-public-surface-reconciliation.md
• scripts/ci/reconcile_repository_metadata.py
• tests/test_repository_metadata_workflow_pages.py

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/metadata-preserve-workflow-pages

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[devin-ai-integration]

Note

This report is out of date. Scroll down for Devin Review's latest report on this PR.

Devin Review found 1 new potential issue.

[devin-ai-integration]

Devin Review found 0 new potential issues.

[seonghobae]

QUEUE_SATURATION_CHICKEN_EGG verified on exact head 78a0791339147e18afcc443ebe88213cfa83184b against protected main@09090e98ca6fe34ee0ab8a0a8145d7af0a0bb9aa. GitHub reports the head mechanically mergeable; every review thread is resolved; Devin reviewed this exact post-reconciliation head after its 18:35 UTC two-parent merge and reported 0 new potential issues, and the exact-head Devin commit status is success. The head is a normal non-force reconciliation whose second parent is current protected main; the only reconciliation delta relative to the prior owner head is the already-merged #1631 Pingora redirect hardening/test, while #1628's reviewed workflow-Pages fixes remain intact. Its substantive findings—partial metadata mutation before workflow-Pages validation, directory/listing accepted as source evidence, stale ADR/runbook, and redirect-regression mismatch—were fixed test-first or source/docs-first as appropriate and explicitly resolved by Devin. Exact-head required workflows have been generated but remain queued/pending with no failing current-head check; the repository currently has 890 queued Actions runs. This PR itself also repairs stale PR validation by using a PR-stable concurrency lineage with cancel-in-progress only for pull_request runs, while preserving non-cancellable trusted scheduled apply. The remaining admission blocker is therefore saturated Actions capacity, not a source/security/provenance defect. Merge must bind this exact head; predecessor checks are not being promoted to current-head success.