Deleting a page and replacing with an xref evades the "deleted page" check

[shainaraskas]

Describe the bug

these two PRs didn't trigger an error for deleted pages:

elastic/docs-content#2989
elastic/docs-content#2811

both of them deleted a page, but added an equivalent xref in the sidebar. CI passed cleanly. when the PRs were merged, the pages 404'd

note: the crosslinks within the repo were already cleaned up. does the deleted page logic still trip if there are no incoming links? I want to test this but want to log this bug asap

Expected behavior

you can't run or hide from the "deleted page with no redirect" error

Steps to reproduce

No response

Tooling

• docs-builder
• migration tooling
• I'm not sure

[natasha-moore-elastic]

Another PR where a file was renamed without redirects but CI checks passed: elastic/docs-content#3318

[shainaraskas]

elastic/docs-content#5212

This PR deleted a page without a redirect, resulting in a 404, with no errors
https://www.elastic.co/docs/solutions/observability/incident-management/create-manage-cases

[shainaraskas]

the actual cause is that we are not doing redirect checks at the root of docs-content

being fixed in #3316

[cotti]

Triage update — still reproducible on main (xref hypothesis was a red herring)

The "deleted page → no redirect" check does not read toc.yml or any incoming-link state. Replacing a file: entry with a crosslink: does not satisfy or suppress the redirect requirement.

The actual bypass is a path-prefix bug in CI mode for repos where the docset lives at the repo root (e.g. elastic/docs-content):

// src/authoring/Elastic.Documentation.Refactor/Tracking/IntegrationGitRepositoryTracker.cs:12
private string LookupPath { get; } = $"{lookupPath.Trim(['/', '\\'])}/";

When the docset is at the repo root, LocalChangesService passes lookupPath = ".", which becomes "./". PR paths in DELETED_FILES look like deploy-manage/foo.md — they don't start with "./", so every entry is filtered out. ValidateRedirects sees zero deletions and exits cleanly. Local runs (LocalGitRepositoryTracker) use real git diff and aren't affected by the prefix bug.

Other relevant code

• Validator: src/authoring/Elastic.Documentation.Refactor/Tracking/LocalChangesService.cs lines 64–87
• Missing redirects.yml → success (Ensure diff validate returns no error if redirects.yml is not found #1940): same file, lines 29–33
• IsExcluded skip (Skip redirect validation for docset-excluded paths #3095): lines 75 area
• Composite action: actions/diff-validate/action.yml

Existing fix

A fix already exists on the unmerged branch fix/diff-validate-docset-at-root (fc84db91, f6be1ea5, 223d560c) with a NormalizeLookupPath and tests including the docs-content regression case (troubleshoot/deployments/serverless.md).

Proposed plan

1. Merge the existing fix branch (after re-checking it still applies cleanly).
2. Tighten missing-redirects.yml policy: if DELETED_FILES contains .md deletions and redirects.yml is absent, fail with a clear diagnostic instead of returning success.
3. Fix local rename emission in LocalGitRepositoryTracker.GetCommitChanges (lines 58–62): emit RenamedGitChange, not bare GitChange, so authors see rename-without-redirect failures locally.
4. Add E2E regression test simulating the docs-content layout: docset at root, deleted .md, no redirect, unrelated crosslink: added to nav.
5. Docs: add a note to docs/contribute/redirects.md clarifying that swapping file: → crosslink: does not remove the need for a redirect for the old URL.

Open questions

• Should the lenient missing-redirects.yml behavior from Ensure diff validate returns no error if redirects.yml is not found #1940 stay or revert? Lenient mode helps initial onboarding of a repo; strict mode prevents this exact bug class. A "strict if any deletions detected" middle-ground seems right but I'd like a maintainer call.
• Writers/docs-team: is replacing a local page with an xref ever a legitimate alternative to a redirect (e.g., content moved to another repo)? Today, no — the old URL still 404s. If yes, the validator would need to recognize this transition.

---

AI-assisted analysis from current main.