docs: capture three learnings from the latest review-heavy PRs

[marcusrbrown]

Three reusable learnings distilled from recently merged PRs, plus a cross-link pass tightening the privacy-gate doc graph.

• Safe workflow consolidation — when collapsing two scheduled workflows into one, surface area should go down, and safety survives only if you trace each invariant and each remaining caller of any shared interface rather than assuming the merge preserved them; a retired workflow silently drops its dispatch entry point, notification accuracy, and concurrency fencing unless each is accounted for.
• Requirements docs that survive verification — make checkable claims, name closed-schema dual-source constraints explicitly (both the type union and the runtime validator set must move together), record dissent rather than erasing it, and surface sequencing gaps between removing infra and standing up its replacement.
• Safely deleting a superseded signal path — removal is safe only when there are no remaining callers, the replacement covers every condition the old path handled, shared dependencies survive for their other consumers, and nothing dangles.

The privacy-gate correctness learning already lived across several existing docs, so instead of a fourth doc this adds a See-also index on the canonical privacy-gate doc and reciprocal links so the related patterns reference each other.

Closes #3582
Closes #3583
Closes #3584
Closes #3585

[fro-bot]

The structural shape here is a doc-graph densification: three new learnings plus reciprocal See-also edges that turn a loose pile of privacy-gate and workflow-removal notes into a navigable cluster. No code, no workflows, no dependencies, no executable surface — the entire blast radius is markdown.

I verified the thing most likely to be wrong in a cross-link pass: every relative link target. All 11 files' referenced paths resolve against the live tree — verify-whole-public-perimeter, observability-before-structural-change, loose-then-tight-schema-migration-pattern, private-repo-dispatch-visibility-gate, the two new sibling docs, and the rest all exist, and the ../ depths match each source file's directory. No dangling edges.

Frontmatter on both new docs (requirements-doc-survives-verification, safe-superseded-workflow-removal, workflow-consolidation-invariant-trace) matches the established schema — problem_type, category, severity, verified, tags, applies_when all present and consistent with neighbors.

The consolidation doc's own guidance — trace every caller, grep before retiring a shared interface — is exactly the discipline I'd want applied to the workflow changes these docs describe; it's self-consistent with docs/solutions/workflow-issues/workflow-consolidation-invariant-trace-2026-06-24.md.

Verdict: PASS

Blocking issues

None.

Non-blocking concerns

• docs/solutions/best-practices/credential-mint-time-permission-scoping-2026-06-22.md (+98–100): the new See-also entry soft-wraps the link text across three lines with a hanging em-dash. CommonMark renders it fine, but it reads ragged next to the single-line entries above it. Cosmetic; ignore unless you're already touching the file.
• workflow-consolidation-invariant-trace carries an "Operational pitfall: cheapest class of CI red" section about formatter-only failures. It's flagged as a sibling lesson, not co-equal, so it's appropriately fenced — no action needed, just noting the scope creep is self-aware.

Missing tests

None. Documentation-only change; no behavior to cover. There is no markdown link-check workflow in this repo, so link integrity was verified manually rather than by CI — worth a future lychee/markdown-link-check job if this doc graph keeps growing, but out of scope here.

Risk assessment: LOW

Markdown-only, additive, all cross-links resolve, frontmatter conforms. The worst plausible failure is a broken relative link, and there are none. Nothing touches automation, secrets, or the action runtime.

---

Run Summary

Field	Value
Event	pull_request
Repository	fro-bot/.github
Run ID	28078441090
Cache	hit
Session	ses_107cb489cffeV4r6o0w57YyTOC