docs(contracts): stop synced contract docs linking to unsynced siblings by stranske · Pull Request #2875 · stranske/Workflows

stranske · 2026-08-01T15:04:19Z

Why

docs/contracts/run-contract-v1.md and docs/contracts/identity-map-conventions.md are synced to consumer repos, but they carried relative links to research-backplane-contract.md and langsmith-fleet-v1.md, which are deliberately not synced — .github/sync-manifest.yml:803-806:

The registry (config/backplane_participants.json) and the program doc (docs/contracts/research-backplane-contract.md) are intentionally NOT synced (Workflows-only single source of truth)

So in every consumer those links dangle. It went unnoticed until the first sync PR delivered these docs to a repo that actually tests links: stranske/Collab-Admin#961 failed tests/test_docs_links.py::test_docs_links_are_resolvable on exactly those three links —

- docs/contracts/identity-map-conventions.md -> ./research-backplane-contract.md
- docs/contracts/run-contract-v1.md          -> ./research-backplane-contract.md
- docs/contracts/run-contract-v1.md          -> ./langsmith-fleet-v1.md

— blocking an otherwise config-only sync PR (all four of those docs are absent from Collab-Admin today, so this sync was their first delivery).

What changed

The three links now point at canonical github.com/stranske/Workflows/blob/main/... URLs, with an inline note that those docs are Workflows-only. This keeps the deliberate no-sync decision fully intact while making the synced docs self-contained.

Untouched: research-backplane-contract.md and langsmith-observability-contract.md keep their relative links, because they are not synced and their siblings are local to this repo. The bare `research-backplane-contract.md` code reference at run-contract-v1.md:203 is not a link and needed no change.

Verification

Rather than fix only the three reported links, I scanned every synced doc against the compiled manifest:

for each synced *.md: every ](./*.md) target must also be synced
  -> OK: every relative .md link in a synced doc points at another synced doc

pytest tests/docs/ → 34 passed.

Follow-up

Once this merges, Collab-Admin's sync PR needs the refreshed docs to go green — a maint-68 run will update its sync branch.

A guard for this class of defect (assert no synced doc relative-links to an unsynced target, using the same compiled-manifest scan) would stop it recurring; not added here to keep the fix reviewable.

🤖 Generated with Claude Code

docs/contracts/run-contract-v1.md and identity-map-conventions.md are synced to consumer repos, but carried relative links to research-backplane-contract.md and langsmith-fleet-v1.md, which are deliberately Workflows-only ("intentionally NOT synced ... single source of truth", .github/sync-manifest.yml:803-806). In any consumer the links therefore dangle. That broke the very first sync PR to deliver these docs to a repo with a docs-link test: stranske/Collab-Admin#961 failed tests/test_docs_links.py::test_docs_links_are_resolvable on exactly those three links, blocking an otherwise config-only sync. Point the three links at the canonical Workflows URLs instead, and note inline that those docs are Workflows-only. This keeps the deliberate no-sync decision intact while making the synced docs self-contained. Verified with a scan over the compiled manifest: every relative .md link in every synced doc now resolves to another synced doc. Only these three were broken; research-backplane-contract.md and langsmith-observability-contract.md keep their relative links because they are not synced. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

cursor · 2026-08-01T15:04:23Z

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

coderabbitai · 2026-08-01T15:04:27Z

Warning

Review limit reached

You’ve reached a temporary PR review limit under our Fair Usage Limits Policy.

Your recent review volume is higher than typical usage, so adaptive limits are currently applied.

Next review available in: 12 minutes

Your organization has reached its usage spending cap. Adjust your spending cap in the billing tab.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 35ca31d4-c5f3-49fd-ac37-c6327d05df40

📥 Commits

Reviewing files that changed from the base of the PR and between a84a558 and 3e2aa2e.

📒 Files selected for processing (2)

docs/contracts/identity-map-conventions.md
docs/contracts/run-contract-v1.md

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

stranske-keepalive · 2026-08-01T15:04:40Z

Workflow source needed

PR #2875 needs either a linked GitHub issue or one valid non-issue Workflow Source before PR metadata automation can manage it safely.

Please do one of:

Add  or a normal Closes #123 / Related to #123 line.
Check one Workflow Source option in the PR body.
Add a hidden marker such as , , , , or .
Add a workflow source label such as workflow:source-direct-pr, workflow:source-local-request, workflow:source-review-followup, workflow:source-sync, or workflow:no-automation.

Once a valid source is present, this warning will not be reposted.

agents-workflows-bot · 2026-08-01T15:05:29Z

Gate fast-pass: docs-only change detected; heavy checks skipped.

agents-workflows-bot · 2026-08-01T15:05:34Z

Automated Status Summary

Head SHA: ac0e806
Latest Runs: ⏳ pending — Gate
Required contexts: Gate / gate
Required: core tests (3.12): ⏳ pending, core tests (3.13): ⏳ pending, docker smoke: ⏳ pending, gate: ⏳ pending

Workflow / Job	Result	Logs
(no jobs reported)	⏳ pending	—

Updated automatically; will refresh on subsequent CI/Docker completions.

Keepalive checklist

Scope

No scope information available

Tasks

No tasks defined

Acceptance criteria

No acceptance criteria defined

Copilot

Pull request overview

Updates synced contract documentation so consumer repos don’t receive dangling relative links to Workflows-only (intentionally unsynced) contract siblings, avoiding downstream doc-link test failures in consumers.

Changes:

Replaces relative links to research-backplane-contract.md and langsmith-fleet-v1.md with canonical github.com/stranske/Workflows/blob/main/... URLs in synced docs.
Adds inline “Workflows-only; not synced to participants” notes where the linked targets are intentionally unsynced.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
docs/contracts/run-contract-v1.md	Switches two sibling-doc references from relative to canonical GitHub URLs and adds “Workflows-only” notes.
docs/contracts/identity-map-conventions.md	Switches the ownership-doc reference from relative to a canonical GitHub URL.

Copilot AI review requested due to automatic review settings August 1, 2026 15:04

stranske enabled auto-merge (squash) August 1, 2026 15:04

stranske temporarily deployed to agent-standard August 1, 2026 15:04 — with GitHub Actions Inactive

Copilot started reviewing on behalf of stranske August 1, 2026 15:04 View session

stranske merged commit 5084eb7 into main Aug 1, 2026
42 checks passed

stranske deleted the fix/synced-contract-docs-dangling-links branch August 1, 2026 15:05

Copilot AI reviewed Aug 1, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs(contracts): stop synced contract docs linking to unsynced siblings - #2875

docs(contracts): stop synced contract docs linking to unsynced siblings#2875
stranske merged 1 commit into
mainfrom
fix/synced-contract-docs-dangling-links

stranske commented Aug 1, 2026

Uh oh!

cursor Bot commented Aug 1, 2026

Uh oh!

coderabbitai Bot commented Aug 1, 2026

Review limit reached

Uh oh!

stranske-keepalive Bot commented Aug 1, 2026

Uh oh!

agents-workflows-bot Bot commented Aug 1, 2026

Uh oh!

agents-workflows-bot Bot commented Aug 1, 2026

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

stranske commented Aug 1, 2026

Why

What changed

Verification

Follow-up

Uh oh!

cursor Bot commented Aug 1, 2026

Uh oh!

coderabbitai Bot commented Aug 1, 2026

Review limit reached

Uh oh!

stranske-keepalive Bot commented Aug 1, 2026

Workflow source needed

Uh oh!

agents-workflows-bot Bot commented Aug 1, 2026

Uh oh!

agents-workflows-bot Bot commented Aug 1, 2026

Automated Status Summary

Keepalive checklist

Scope

Tasks

Acceptance criteria

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants