Skip to content

docs: fix three relative links that never resolved - #37627

Merged
fabrizzio-dotCMS merged 1 commit into
mainfrom
issue-37577-broken-links
Sep 18, 2026
Merged

fabrizzio-dotCMS merged 1 commit into
mainfrom
issue-37577-broken-links

Conversation

@fabrizzio-dotCMS

@fabrizzio-dotCMS fabrizzio-dotCMS commented Sep 18, 2026

Copy link
Copy Markdown
Member

What

Fixes the three broken documentation links found while auditing Scout's slice for #37577. All three share one cause: the link was written as if the containing file sat at the repo root.

File Link Resolved to Now
.specify/memory/constitution.md:39 docs/core/SECURITY_PRINCIPLES.md .specify/memory/docs/core/… ../../docs/core/…
.specify/memory/constitution.md:47 docs/core/ROLLBACK_UNSAFE_CATEGORIES.md .specify/memory/docs/core/… ../../docs/core/…
core-web/CLAUDE.md:106 docs/frontend/STYLING_STANDARDS.md#form-fields core-web/docs/frontend/… ../docs/frontend/…

The constitution is loaded by every skill, and both of its targets are Critical Rules material — so the two rules it most wants a reader to follow were the two it could not reach.

For core-web/CLAUDE.md, line 142 of the same file already used ../docs/frontend/ for a sibling doc, so this just matches the convention already there. The #form-fields anchor exists at STYLING_STANDARDS.md:149.

Out of scope, worth knowing

A repo-wide sweep of all 539 tracked .md files turned up 77 broken relative links beyond these three. None are in docs/ — that tree is clean. The breakdown:

  • 65 in specs/ — mostly sibling references (./research.md, ../data-model.md) in spec working directories where the referenced artifact was never created or has since moved.
  • 9 in .github/ — including 8 written with a leading slash (/CLAUDE.md, /CONTRIBUTING.md), which does not resolve on github.com.
  • 1 each in README.md, core-web/libs/portlets/edit-ema/ARCHITECTURE.md, and test-jmeter/.

Left alone deliberately: this PR is scoped to the three links #37577 names, and specs/ is a different kind of artifact with different owners. Flagging it for the gap backlog (#37580) instead — an automated link check would catch all 77 and stop them coming back, which is the same argument as the reachability check in #37578.

Testing

Documentation only. Every link in both changed files was re-resolved after the edit; all six now point at real files, and the one anchor reference was confirmed against its target heading.

Refs #37577

🤖 Generated with Claude Code

This PR fixes: #37577

All three were written as if the containing file sat at the repo root.

`.specify/memory/constitution.md` linked `docs/core/SECURITY_PRINCIPLES.md` and
`docs/core/ROLLBACK_UNSAFE_CATEGORIES.md`, which resolve to
`.specify/memory/docs/core/...`. The constitution is loaded by every skill and
both targets are Critical Rules material, so the two rules it most wants a reader
to follow were the two it could not reach. Now `../../docs/core/`.

`core-web/CLAUDE.md:106` linked `docs/frontend/STYLING_STANDARDS.md#form-fields`,
resolving to `core-web/docs/frontend/...`. Line 142 of the same file already used
`../docs/frontend/` for a sibling doc, so this now matches the convention already
in the file. The `#form-fields` anchor exists (STYLING_STANDARDS.md:149).

Refs #37577

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@fabrizzio-dotCMS fabrizzio-dotCMS added the Area : Documentation PR changes documentation files label Sep 18, 2026
@github-actions github-actions Bot mentioned this pull request Sep 18, 2026
10 tasks
@github-actions github-actions Bot added the Area : Frontend PR changes Angular/TypeScript frontend code label Sep 18, 2026
@claude

claude Bot commented Sep 18, 2026

Copy link
Copy Markdown
Contributor

Claude finished @fabrizzio-dotCMS's task in 28s —— View job


Review complete

  • Read PR diff against origin/main
  • Verify all three link targets exist
  • Verify the #form-fields anchor resolves
  • Verify relative path arithmetic from each file's location
  • Confirm convention consistency

I verified each edited link by re-resolving it from its file's location:

File:line New link Resolves to Exists?
.specify/memory/constitution.md:39 ../../docs/core/SECURITY_PRINCIPLES.md repo-root docs/core/…
.specify/memory/constitution.md:47 ../../docs/core/ROLLBACK_UNSAFE_CATEGORIES.md repo-root docs/core/…
core-web/CLAUDE.md:106 ../docs/frontend/STYLING_STANDARDS.md#form-fields repo-root docs/frontend/…
  • .specify/memory/ is two levels deep, so ../../ correctly lands at the repo root — both docs/core/ targets exist.
  • core-web/ is one level deep, so ../ is correct; this also matches the existing convention at core-web/CLAUDE.md:142 (../docs/frontend/TESTING_PERFORMANCE.md).
  • The #form-fields anchor maps to ## Form Fields at docs/frontend/STYLING_STANDARDS.md:149 — GitHub slugifies that heading to form-fields, so the anchor resolves.

New Issues

No issues found. All six links across the two changed files resolve to real files, and the anchor matches its target heading. The fix is correct, minimal, and consistent with existing conventions.

The out-of-scope call is reasonable — keeping this PR to the three links #37577 names and routing the other 77 to the #37580 backlog is the right scoping. An automated markdown link check would be the durable fix.

· issue-37577-broken-links

@fabrizzio-dotCMS
fabrizzio-dotCMS added this pull request to the merge queue Sep 18, 2026
Merged via the queue into main with commit d1a5265 Sep 18, 2026
52 checks passed
@fabrizzio-dotCMS
fabrizzio-dotCMS deleted the issue-37577-broken-links branch September 18, 2026 18:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

AI: Safe To Rollback Area : Documentation PR changes documentation files Area : Frontend PR changes Angular/TypeScript frontend code

Projects

Status: No status

Development

Successfully merging this pull request may close these issues.

M1 — Fix Scout contradictions

2 participants