[dmccoystephenson]

Summary

• check_local_links() in scripts/check_docs.py now names the offending doc by its path relative to the repo root (doc.relative_to(REPO_ROOT).as_posix()) instead of its basename (doc.name). Before this change, a broken link in scripts/README.md was reported as README.md: broken relative link -> …, which points at the root README instead. Root-level docs get the same message as before.
• test_link_resolves_relative_to_containing_doc previously asserted the basename-only message (SAME.md: for a file at docs/SAME.md). It now asserts docs/SAME.md:.
• New regression case test_same_named_docs_are_told_apart_by_path: a root README.md and a scripts/README.md with a broken link. The error must name scripts/README.md.

Closes #168

Skipped issues: every other open issue was left alone this cycle. Each one is either a template-behavior change, which can't be validated in a headless dispatch and so could not merge autonomously (#109), or the CLAUDE.md edit in #106, which needs separate authorization. A Stage A documentation sweep was done first: README, CONTRIBUTING, SECURITY, the PR/issue templates and scripts/README.md were checked against create-dev-loop.md, and every RESEARCH.md ship date was checked against GitHub's mergedAt. No drift was found. This bug turned up as an "unhelpful error message" during the same sweep.

Research grounding

No RESEARCH.md finding applies. The change only affects the wording of a CI error message and doesn't touch the template or any phase definition.

Doc sync check

No doc needed changes. No document quotes the old message format (checked by grepping for broken relative link), and CLAUDE.md/CONTRIBUTING.md describe the check as "relative links between the repo's own docs resolve", which is still accurate.

Test plan

• python3 scripts/check_docs.py → "Doc consistency check passed."
• python3 -m unittest discover -s tests → Ran 42 tests … OK
• Regression proof (revert-and-run): with scripts/check_docs.py checked out from origin/main, two tests fail (test_link_resolves_relative_to_containing_doc, test_same_named_docs_are_told_apart_by_path). With the fix restored, all 42 pass.
• No /create-dev-loop behavioral run is needed: the template is unchanged.

Merge note: scripts/check_docs.py is on this repo's dev-loop do-not-auto-merge list (it is the only mechanical doc gate), so this PR is left open for maintainer review rather than merged autonomously.

This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

🤖 Generated with Claude Code

---

drafted by Claude on behalf of Daniel Stephenson

[dmccoystephenson]

Self-review rubric (scored against CI run 40634734724 on the PR head and the diff):

• Scope: PASS. Two files are changed: the one-line fix in scripts/check_docs.py:112, and the test file. No unrelated reformatting.
• Tests-new: PASS. No new public function was added. The changed behavior is covered by the updated assertion and the new test_same_named_docs_are_told_apart_by_path.
• Tests-fix: PASS. Checked by revert-and-run (git checkout origin/main -- scripts/check_docs.py). With the fix reverted, FAILED (failures=2), and exactly the two tests named in the PR body fail. With the fix restored, Ran 42 tests … OK. The pre-existing assertion change at tests/test_check_docs.py:280 (SAME.md: → docs/SAME.md:) also records the FAIL→PASS by itself.
• Sibling structure: PASS. The new test follows the neighboring CheckLocalLinksTests pattern: a tempdir fixture, REPO_ROOT swapped in and restored in tearDown, and an exact-message assertion.
• Sibling renames: N/A. Nothing was renamed.
• Docs: PASS. Grepping for broken relative link finds no document that quotes the message format. CLAUDE.md, CONTRIBUTING.md and the PR template describe the check at a level that is still accurate.
• Issue resolution: PASS. check_local_links names only the basename, so a broken link in scripts/README.md is reported as README.md #168 asks for the repo-relative path plus a regression case with same-named docs. Both are in the diff.
• CI: PASS. doc-consistency passed on the head commit.
• Placeholder parity / README Step parity / Fence escaping / Phase numbering / Version comments: N/A. create-dev-loop.md and README.md are untouched.
• Research grounding: PASS. The PR body says no finding applies, which fits an error-message fix outside the template.
• No back-ported specifics / gardener interface / Retrofit note / Behavioral validation: N/A. Steps and template are unchanged.

Judgment call: relative_to(REPO_ROOT) raises ValueError if rglob ever yields a path outside REPO_ROOT. That can only happen through a symlinked directory, and rglob doesn't follow those by default, so the risk is accepted rather than guarded against.

Merge status: scripts/check_docs.py is on the do-not-auto-merge list, so this PR is left for maintainer approval even though the run is pre-authorized to merge.

This comment was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

---

drafted by Claude on behalf of Daniel Stephenson