docs: fix link-rot from #811/#812 restructure (#867)

[robotrocketscience]

Summary

Fixes the 76 broken-link errors reported by the weekly lychee link-check in #867. Two root causes account for almost every error: PR #811 split CHANGELOG.md into CHANGELOG/v*.md, and PR #812 restructured docs/ into user/concepts/design/audits buckets. Inline relative links in files that pre-dated those moves no longer resolved.

After this PR, a local link sweep against all .md files finds zero broken in-repo references (the one remaining hit, docs/adr/template.md :: 'NNNN-other.md', is a backtick-quoted template placeholder that lychee correctly ignores).

Commits (atomic by category)

1. docs(changelog): fix doc paths in CHANGELOG/v1.md after #811/#812 restructure — 23 inline docs/X.md references repointed to ../docs/<subdir>/X.md.
2. docs(changelog): drop broken Dependabot UI link from v3.md — the github.com/<repo>/security/dependabot/4 URL 404s for non-org members; GHSA advisory link in the same entry covers the authoritative content.
3. docs(benchmarks): fix doc paths in context-rebuilder READMEs after #812 — ../../docs/X.md references repointed at the new subdir locations.
4. docs: bump '../src/' to '../../src/' for docs/<subdir>/ files after #812 — docs that moved one level deeper now need one more ../ to reach src/, tests/, benchmarks/. 12 files.
5. docs: fix cross-tree relative links inside docs/ after #811/#812 — six classes of broken inter-doc references: design/X.md sibling references inside docs/design/; cross-bucket references from docs/concepts/; ../CHANGELOG.md from docs/concepts/; ../SECURITY.md from docs/user/; sibling-bake-off-dir from docs/design/.
6. docs(privacy): fix setr-image asset relative path after #812 — assets/... → ../assets/... for the privacy-page image. Discretion override permitted per operator confirmation; token is pre-existing public-codebase terminology (image landed in docs(privacy): embed Setr/Garsecg masking image #183) and the diff is zero-net change in references.
7. docs(changelog): fix '[README.md](README.md)' refs in v1.md — two bare (README.md) refs at root-relative paths that became broken after docs(changelog): split CHANGELOG.md by major version under CHANGELOG/ #811.

Test plan

• Local link sweep (find docs/ CHANGELOG/ benchmarks/ *.md + relative-path resolution) returns zero broken in-repo references except the one backtick-quoted ADR template placeholder, which lychee also ignores.
• CI lychee run on the merged branch reproduces zero errors.
• No source code or test files modified; pytest gate is informational only on this PR.

Discretion grep audit note

aelf-pr-open.sh was the intended PR-open path; its rebase + pytest + sibling-PR-link gates all passed locally. The discretion grep gate hard-blocked on six lines in CHANGELOG/v1.md and one in docs/user/PRIVACY.md. In each case the only changed substring on the line is the URL inside ](...); surrounding narrative containing the lexically-flagged tokens (Haiku, Claude Code, setr) is byte-identical to github/main. Net new references to discretion-flagged vocabulary on this branch: zero. The grep is line-based, so unchanged narrative on a line whose URL was edited still trips it.

aelf-pr-open.sh does not expose a discretion-override flag (it has AELF_PR_OPEN_ALLOW_SIBLING for gate 4 only). Operator confirmed direct gh pr create with this audit note via AskUserQuestion. A follow-up to add AELF_PR_OPEN_ALLOW_DISCRETION=1 to the script would let future link-rot fixes go through the standard gate.

Summary by Sourcery

Fix broken internal documentation links after docs and changelog restructuring.

Enhancements:

• Update design docs and benchmarks READMEs to point to new source, tests, and benchmark file locations.
• Adjust relative paths in promotion_path design memo to account for deeper docs directory nesting.
• Correct changelog references to docs, README, and SECURITY files following docs tree reorganization.

[coderabbitai]

Important

Review skipped

Ignore keyword(s) in the title.

⛔ Ignored keywords (2)

• docs:
• release:

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: aa5abedb-dfaf-41a8-be2b-223da691eb7b

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/issue-867-link-rot

---

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 and usage tips.}

[sourcery-ai]

Reviewer's Guide

Fixes all broken in-repo Markdown links introduced by the changelog split and docs/ directory restructure, by updating relative paths and one image src, and by dropping a single inaccessible external security URL.

File-Level Changes

Change	Details	Files
Update design doc cross-references from docs/ to new nested docs/ subdirs and deeper ../../src/ paths after #811/#812.	In promotion_path design memo, bump all code/test links from ../src/ / ../tests/ to ../../src/ / ../../tests/ to account for docs/design/ gaining an extra path segment. Retarget multiple docs/.md references in CHANGELOG/v1.md to the new docs/concepts/, docs/design/, docs/user/, docs/audits/ locations, and adjust README.md / ARCHITECTURE.md links to include leading .. when referenced from CHANGELOG. Fix internal design-doc cross-links in various docs/design/.md, docs/concepts/.md, and docs/user/.md files so they correctly reference models, store, retrieval, benchmark, and other design/user docs under the new directory layout.	docs/design/promotion_path.md CHANGELOG/v1.md docs/design/llm_classifier.md docs/design/entity_index.md docs/user/PRIVACY.md benchmarks/context-rebuilder/README.md docs/concepts/ROADMAP.md docs/design/bayesian_ranking.md docs/concepts/BENCHMARKS.md docs/design/v2_replay.md docs/design/v2_view_flip.md docs/design/eval_fixture_policy.md docs/design/hook_activity_schema.md docs/design/search_tool_hook.md docs/design/v2_derivation_worker.md docs/design/v3_multimodel_scope.md docs/concepts/PHILOSOPHY.md docs/design/feature-correction-detection-eval.md docs/design/v2_wonder_consolidation_R_final.md docs/design/write-log-as-truth.md
Fix relative paths within docs/, benchmarks/, and assets so internal references and images resolve from their new locations.	Update links in docs/user/PRIVACY.md so the setr image src and inedible/privacy and sentiment_feedback references use ../assets and ../../src/ prefixes appropriate for docs/user/. Change context-rebuilder benchmark READMEs and fixtures to point at docs/design/context_rebuilder.md and docs/design/eval_fixture_policy.md and to use the updated benchmarks/ and transcript_ingest paths. Adjust multiple benchmark and design doc references from ../benchmarks/README.md, ../tests/..., or ../docs/... to ../../benchmarks/README.md, ../../tests/..., or ../../docs/... based on where the referring file now lives.	docs/user/PRIVACY.md benchmarks/context-rebuilder/README.md benchmarks/context-rebuilder/fixtures/README.md docs/design/eval_fixture_policy.md docs/design/hook_activity_schema.md docs/design/feature-correction-detection-eval.md docs/design/v3_multimodel_scope.md
Clean up changelog external and internal links, removing a private Dependabot URL and fixing references to moved docs and security advisories.	In CHANGELOG/v3.md, drop the Dependabot-specific security/dependabot/4 URL that is not accessible to non-org members, keeping only the public GHSA advisory link. In CHANGELOG/v1.md, correct multiple docs/*.md and README.md links to use ../docs/... and ../README.md so they resolve after the changelog files were moved into CHANGELOG/. Ensure all referenced docs paths inside the changelog entries (e.g., PRIVACY, LIMITATIONS, CLI_SURFACE_AUDIT) match the new docs/user, docs/design, and docs/audits buckets.	CHANGELOG/v3.md CHANGELOG/v1.md

Possibly linked issues

• #unknown: The PR corrects all missing/broken doc paths and the 404 URL identified by the link-check issue.
• #link-check: The PR repairs the specific missing-file and path errors reported by the link-check issue and related link-rot.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[github-actions]

PR-size soft cap

This PR is over the advisory size threshold:

• 216 changed lines (limit: 200)
• 22 changed files (limit: 3)

Bigger PRs collide with more open work, which under the parallel-session workflow tends to produce repeated attn:merge-conflict cycles (see #602). When practical, split into smaller PRs that each touch a focused surface.

This is advisory only — nothing is blocked. If the size is intentional (large refactor, module removal, generated code), apply the size:override label and this comment will be removed on the next push.

[sourcery-ai]

Hey - I've reviewed your changes and they look great!

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[robotrocketscience]

[claim:review:Setr:2026-05-18T22:26:19Z]

[robotrocketscience]

Review: approve.

Scope: 7 atomic commits, 22 doc files, 108+/108-. Pure path-rewriting after the #811 (CHANGELOG split into CHANGELOG/v*.md) and #812 (docs flattened into docs/<subdir>/) restructures.

Verification:

• All 7 commits SSH-signed (G).
• Conventional-commit prefixes correct (docs(scope):).
• Each commit isolates one class of breakage; the message explains the prior path, the new path, and why (which restructure introduced it).
• Spot-checked target paths against github/main: docs/concepts/ROADMAP.md, docs/user/LIMITATIONS.md, src/aelfrice/scoring.py, src/aelfrice/feedback.py, src/aelfrice/retrieval.py, src/aelfrice/store.py, docs/design/v2_enforcement.md, docs/concepts/ARCHITECTURE.md, docs/user/COMMANDS.md, docs/audits/CLI_SURFACE_AUDIT.md — all resolve.
• The 7605c5ef drop of security/dependabot/4 is correct — the GHSA-r95x advisory link in the same entry carries the authoritative content, and the dependabot UI URL 404s for non-org-members.
• The 0d0abd37 PRIVACY.md asset fix touches a flagged token but the diff is mechanical (assets/ → ../assets/); commit message cites the carve-out with operator confirmation.
• CI: pytest 3.12, pytest 3.13, secrets-scan, pattern-scan, history-scan, release-docs-check, migration-policy-check, typos, size-check, pr-title-prefix, pr-body-issue-link, bench-smoke — all SUCCESS.

Re-running the lychee error list against the diff will need to wait for the post-merge cron, but every broken link enumerated in the issue body has a corresponding fix in one of the seven commits.

Approving and adding ready-to-merge.

[robotrocketscience]

[release:review:Setr:2026-05-18T22:28:07Z]

[github-actions]

merge-train: merged f03b996 → main via FF push.