ci: reject retired repository links in active documentation

[devantler]

🤖 Generated by the Agentic Engineer

Why

Active documentation can silently send readers to a retired workflow repository because CI does not check those links.

What

Add the shared read-only link guard to required CI, with controls proving that retired links and incomplete scans are rejected.

Fixes #523

[devantler]

🤖 Generated by the Agentic Engineer

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[coderabbitai]

Navigate logical layers of code changes, visualize relationships, and explore their blast radius.

Warning

Review limit reached

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

Next included review available in 37 minutes.

Check out review usage here.

View limit details

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

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 76cfe8cb-0542-4fb3-acd6-b92b4f9b9db3

📥 Commits

Reviewing files that changed from the base of the PR and between 63a8515 and 3205d34.

📒 Files selected for processing (2)

• .github/retired-repo-links.json
• .github/workflows/ci.yaml

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Organization UI
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: 2a42494a-7206-47e0-a69f-0314aced3ec2

📥 Commits

Reviewing files that changed from the base of the PR and between 63a8515 and 4d2ac71.

📒 Files selected for processing (2)

• .github/retired-repo-links.json
• .github/workflows/ci.yaml

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

📜 Recent review details

⏰ Context from checks skipped due to timeout. (8)

• GitHub Check: eligibility
• GitHub Check: dependency-review
• GitHub Check: eligibility
• GitHub Check: Analyze (go)
• GitHub Check: Analyze (javascript-typescript)
• GitHub Check: Analyze (actions)
• GitHub Check: Analyze (go)
• GitHub Check: Analyze (javascript-typescript)

🧰 Additional context used

📓 Path-based instructions (1)

Source excerpt: **Least-privilege permissions.**

📄 CodeRabbit inference engine (AGENTS.md)

Files:

• .github/workflows/ci.yaml

🔇 Additional comments (2)

.github/retired-repo-links.json (1)

1-1: LGTM!

.github/workflows/ci.yaml (1)

455-505: LGTM!

Also applies to: 514-520

---

📝 Walkthrough

Walkthrough

The change adds a versioned configuration for scanning retired repository links in README.md and AGENTS.md. CI runs the pinned validator and checks its scan result, its response to a seeded retired link, and its handling of missing configuration. The required-check aggregator now includes the validator job.

Priority: ⬇️ Low

Merge Risk: ⚪ Minimal · up to 4d2ac

The retired-link guard is configured for README.md and AGENTS.md and included in required checks. No merge-blocking issue was identified.

Architecture Summary

Architecture risk: 🔵 Low · up to 4d2ac

The changed surface does not map to a changed system, dependency edge, entrypoint, or external dependency.

Changed systems: None identified.

Architecture concerns
No architecture-level concerns identified.

Review details

Before / after behavior

• observed — Modified behavior in .github/retired-repo-links.json: Added a versioned configuration listing the repository, its tracked paths, and an empty exceptions list.
• observed — Modified behavior in .github/workflows/ci.yaml: Adds a read-only, 10-minute job that runs the pinned retired-repository link validator and fails unless its scan-complete output is true. It then builds the validator from the pinned source revision and checks that a seeded retired link is rejected with status 1 and the expected diagnostic, and that removing the configuration is refused with status 2 and an invalid-configuration message.
• observed — Modified behavior in .github/workflows/ci.yaml: Adds retired-repo-links to the required-check aggregator’s dependencies and passes its result to the aggregation action; the existing dependencies and unconditional aggregation behavior remain.

---

Important

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Linked Issues check	❓ Inconclusive	Issue #523 requests a read-only guard for README.md and AGENTS.md, with no exceptions, in required CI. The configuration lists both paths and has an empty exceptions list. The PR summary reports a req…	Provide evidence that native CI passes at the reviewed head and after merge.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: CI will reject retired repository links in active documentation.
Description check	✅ Passed	The description explains why the link guard is needed and what it adds to required CI.
Out of Scope Changes check	✅ Passed	The reported changes are limited to the retired-link configuration and its required CI job. Both changes directly implement issue #523. No unrelated changes are identified.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…

Full details: Linked Issues check

Explanation

Issue #523 requests a read-only guard for README.md and AGENTS.md, with no exceptions, in required CI. The configuration lists both paths and has an empty exceptions list. The PR summary reports a required CI job that checks scan completion and tests a seeded retired link and missing configuration. The available evidence does not establish successful native CI at the reviewed head or after merge.

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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.}

[devantler]

🤖 Generated by the Agentic Engineer

@coderabbitai full review

[coderabbitai]

⚠️ Action not completed

Review rate limited.

---

Your included review limit is currently reached under our Fair Usage Limits Policy. This review may still proceed through usage-based billing if eligible. Your next included review will be available in 37 minutes.

[devantler]

🤖 Generated by the Agentic Engineer

Self-review (fallback — CodeRabbit, Codex and Cursor Bugbot unavailable)

Reviewed commit: 3205d34

Provider receipts were freshly authenticated at 2026-10-05T10:43:07Z; direct current-PR reviews, conversation comments, inline comments, threads and complete check-run pages were read.

• CodeRabbit: this PR's exact-head request was rate limited at 2026-10-05T10:28:43Z, with a 37-minute recovery window ending 2026-10-05T11:05:43Z. Provider receipt.
• Codex: the applicable review account reached its code-review usage limit at 2026-10-05T08:40:17Z; the authenticated response states no reset and requires account capacity to recover. Provider receipt.
• Cursor Bugbot: the applicable review user or team hit a usage or spend limit at 2026-10-05T05:09:57Z; the authenticated response states no reset and requires a user or team administrator to restore capacity. Provider receipt.

Verdict: no P0/P1 findings

Independently reviewed both changed files and the immutable bd0035dd8f41fcf1459b878882b8897443f8dc59 validator runtime. The explicit opt-in, scoped documentation configuration, complete-scan output, read-only job and required-check aggregation preserve the existing validation and publication boundaries.

The actual inline refusal script was extracted from this head and executed with the pinned source. The clean consumer scan examined both documents with zero exceptions or retired links; the seeded README link produced exit 1 with its expected diagnostic, and missing configuration produced exit 2. Workflow lint and diff checks passed. Local execution used Go 1.27.1; hosted execution uses the action's declared Go 1.26.8.

CodeRabbit's linked-issue assessment remains inconclusive because native CI at this head and postmerge main verification are still pending. Those acceptance requirements remain in force; this review supplies no CI or merge clearance.

[devantler]

🤖 Generated by the Agentic Engineer

Native evaluation verified for PR head 3205d34c18b78ea44ce7bf9fde7d9a1c9313755b. I read the full completed guard job in CI run 37296507569; it succeeded at 2026-10-05T10:56:54Z using validator pin bd0035dd8f41fcf1459b878882b8897443f8dc59 and Go 1.26.8.

• The clean action checked both scoped documents: 2 text files, 0 historical exceptions, 0 retired links, and 0 skipped binary files. Its validated=true output assertion passed.
• Disposable CLI fixtures copied this consumer's actual configuration, README, and AGENTS. A seeded README link to the retired devantler-tech/reusable-workflows repository required exit 1 and the exact expected README diagnostic; both assertions passed.
• Removing the configuration required exit 2 and an Invalid configuration: diagnostic. Both assertions passed, and the native CLI step printed PASS: clean scan, seeded retired link rejection, and missing configuration refusal.

The negative controls execute the released CLI; this job does not invoke separate negative action steps or test their action outputs. Merged-main verification remains pending.