fix: CI/CD robustness, search path resolution, and test self-sufficiency

[costiash]

Summary

Phase 1 bug fixes addressing CI/CD pipeline issues, working-directory-dependent path resolution, and silently-skipped validation tests.

• CI/CD: Stage paths_manifest.json, auto-generate search index, use python3 consistently, add set -e to build step
• Search: Resolve index path relative to repo root via __file__, not cwd (fixes Content search fails when helper script is called with absolute path #15)
• Helper script: Wrap Python calls in (cd $DOCS_PATH && ...) subshells, replace hardcoded counts with dynamic values
• Tests: Make test_no_deprecated_paths and test_internal_links_in_manifest self-sufficient — they previously skipped silently due to missing fixture data, hiding real validation gaps
• Tests: Use inspect.getsource() instead of fragile __wrapped__ attribute access
• Docs: Replace hardcoded "573 paths" language with dynamic phrasing

Changed files (11)

File	Change
.github/workflows/update-docs.yml	Stage manifest, build search index, python3, set -e
.github/workflows/validate.yml	python → python3
scripts/lookup/search.py	__file__-relative path for search index
scripts/claude-docs-helper.sh	cd subshells, dynamic counts
CLAUDE.md, README.md, install.sh	Remove hardcoded path counts
tests/unit/test_manifest_validation.py	Self-sufficient deprecated path test
tests/validation/test_link_integrity.py	Self-sufficient internal link test
tests/unit/test_lookup_functions.py	inspect.getsource, path-resolution test
tests/integration/test_github_actions.py	CI staging + search index tests

Test plan

• Full test suite: 302 passed, 0 failed, 0 skipped
• Both previously-skipped tests now run and pass
• All CI workflow Python calls use python3
• No Co-Authored-By footers in commit messages

[github-actions]

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
scripts/lookup
search.py					137
Project Total

This report was generated by python-coverage-comment-action

[claude]

PR Review: CI/CD robustness, search path resolution, and test self-sufficiency

Overall this is a well-scoped and well-motivated PR. The three problem areas identified (CI/CD pipeline gaps, cwd-dependent path resolution, silently-skipped tests) are all real bugs, and the fixes are generally correct. A few issues worth addressing before merging:

---

Bugs / Correctness Issues

1. pip vs python3 -m pip inconsistency in update-docs.yml

# After the change:
python3 -m pip install --upgrade pip
pip install -r scripts/requirements.txt   # ← still bare pip

The first line now correctly uses python3 -m pip, but the second line still uses bare pip, which may resolve to pip2 or a different environment on some runners. Should be:

python3 -m pip install --upgrade pip
python3 -m pip install -r scripts/requirements.txt

2. test_internal_links_in_manifest — fragile minimum link count

assert total_links > 100, (
    f"Expected 100+ internal links in docs, found {total_links}. "
    ...
)

This assertion is the only guard that the link-scanning regex is working. On a fresh clone with no downloaded docs (or if the regex pattern changes), total_links will be 0 and the assertion fires — which is the right behavior. However the 100 threshold is undocumented and may be surprising in environments where only a subset of docs is synced. A comment explaining why 100 was chosen (e.g., "even a partial sync has >100 internal links") would help future maintainers.

The 30% broken-link tolerance is also quite generous. It may silently mask real manifest drift. Consider logging the count even when passing so it's visible in CI output.

3. test_no_deprecated_paths — filename mapping may not match actual conventions

The new filename mapping for claude_code category handles the sdk/ prefix explicitly:

if stripped.startswith('docs/en/sdk/'):
    page = 'sdk__' + page
expected_file = f"claude-code__{page}.md"

But this is incomplete — other potential nested paths under claude_code (e.g., future paths with two sub-levels) would not be handled, silently inflating the orphan count rather than failing loudly. The 20% tolerance would likely absorb this, but it makes the test less meaningful. Consider deriving the expected filename from the same function that fetch_claude_docs.py uses (url_to_safe_filename from fetcher/paths.py) rather than reimplementing the logic independently.

---

Minor Issues

4. set -e in "Build search index" step is redundant

- name: Build search index
  run: |
    set -e
    echo "Building full-text search index..."
    python3 scripts/build_search_index.py

GitHub Actions already fails the step on any non-zero exit code. The set -e inside run: | is harmless but unnecessary and may confuse readers into thinking it's doing something special.

5. Search index build failure blocks the entire deploy

The new "Build search index" step has no continue-on-error: true. A failure here (e.g., a malformed .md file or encoding issue) will block the documentation commit entirely, even when the docs themselves were fetched successfully. Given that the search index is an enhancement rather than critical infrastructure, consider adding continue-on-error: true with a warning message if the build fails, similar to the pattern used for the fetch step.

---

What's Good

• Path resolution fix (search.py): Path(__file__).resolve().parent.parent.parent is the correct approach for cwd-independent resolution. The depth (3 levels) matches scripts/lookup/search.py → repo root correctly.
• Subshell pattern in helper script: (cd "$DOCS_PATH" && python3 ...) is the right idiom; correctly isolates the working directory change.
• inspect.getsource() is a meaningful improvement over __wrapped__ attribute access for the path-resolution test.
• Staging paths_manifest.json in the git commit step is an important correctness fix — without it, manifest updates were lost on every sync.
• The integration tests for CI workflow content (TestManifestStaging, TestSearchIndexGeneration, TestHelperScriptPythonCalls) are a nice pattern for keeping the tests and workflows in sync.

---

Summary

Issue	Severity	Required?
pip vs python3 -m pip inconsistency	Medium	Yes
Hard-coded 100-link threshold undocumented	Low	Suggestion
Filename mapping logic duplicates fetcher logic	Low	Suggestion
set -e redundancy	Trivial	No
Search index build blocks full deploy	Low	Suggestion

The core fixes (path resolution, manifest staging, subshell cwd, previously-skipped tests) are all correct and well-tested. Addressing the pip inconsistency is the main item before merging.

[costiash]

All Code Review Items Addressed — Ready to Merge

All 5 items from the code review have been resolved, along with additional documentation and versioning updates.

Review Items Resolved

Item 1: Replace bare pip with python3 -m pip

• Fixed across all 4 workflow files (9 occurrences total)
• Files: update-docs.yml, validate.yml, test.yml, coverage.yml
• Verification: grep -rn '^\s*pip install' .github/workflows/ returns zero lines

Item 2: Document the 100-link threshold and log pass statistics

• Added explanatory comment before assert total_links > 100 in test_link_integrity.py
• Added print() that reports link counts on pass for CI log visibility
• Verification: test output shows Link check passed: 1045 total links, 59 unresolved (5.6%)

Item 3: Reuse url_to_safe_filename instead of duplicating logic

• Replaced 17-line inline mapping block with 2-line import + call
• Added sys.path.insert + from fetcher.paths import url_to_safe_filename (matches pattern in 11 other test files)
• Verified: url_to_safe_filename(path) auto-detects correctly for all 573 manifest paths

Item 4: Remove redundant set -e

• Removed from search index build step in update-docs.yml
• GitHub Actions runs bash with -eo pipefail by default

Item 5: Add continue-on-error: true to search index build

• Added to the "Build search index" step
• Matches existing pattern on the "Fetch latest documentation" step

Additional Changes

Documentation updates:

• Updated test counts from 294 to 302 across README.md, CLAUDE.md, CONTRIBUTING.md
• Fixed stale "629 tests" reference in CONTRIBUTING.md
• Removed last hardcoded doc count (571) in helper script show_version()
• Removed hardcoded 573/571 path counts in CONTRIBUTING.md

Version bump to v0.5.1:

• install.sh: TARGET_VERSION updated from 0.5.0 to 0.5.1
• scripts/claude-docs-helper.sh: ENHANCED_VERSION updated from 0.5.0 to 0.5.1
• Aligns with the Phase 1 plan designation of v0.5.1

Verification Evidence

Check	Result
Full test suite	302 passed, 0 failed (17s)
Bare pip install in workflows	0 occurrences
Hardcoded doc counts in user-facing files	0 occurrences
Helper script --version	Shows v0.5.1 correctly
Helper script --help	Works correctly
Link integrity test output	Prints stats on pass
test_no_deprecated_paths with imported function	Passes

Full Branch Summary (10 commits)

5e814fb fix: address code review items, update docs and bump to v0.5.1
79452f3 fix: replace remaining bare python calls with python3 in CI workflows
94ad0b3 fix: make previously-skipped validation tests self-sufficient
20ca5ea fix: address PR review — python3, set -e, test robustness
fddd64b fix: correct syntax error in helper script test
870ec6c docs: replace hardcoded doc counts with dynamic language
118abbb fix: wrap Python calls with cd and remove hardcoded counts (fixes #15)
a122f67 fix: resolve search index path relative to repo root (fixes #15)
3d26f87 feat: auto-generate search index in CI/CD pipeline
50008af fix: stage paths_manifest.json in CI/CD workflow

All Phase 1 objectives complete. Ready to merge.

[claude]

PR Review: fix/phase1-bug-fixes

Overall this is a solid set of targeted fixes addressing real bugs. The core changes are correct and well-motivated. A few issues worth addressing before merge.

---

What's Working Well

• CI/CD python to python3 -m pip: Correct and important for portability across environments where pip may not be on PATH or may point to a Python 2 pip.
• paths_manifest.json staging fix: The bug was real — the manifest was being regenerated every 3 hours but never committed. The fix (git add -A docs/ paths_manifest.json) is minimal and correct.
• load_search_index() path fix: Using Path(__file__).resolve().parent.parent.parent is the right approach. The previous bare Path("docs/.search_index.json") was fragile. The assumed directory structure (scripts/lookup/search.py → 3 levels up → repo root) is correct for this project.
• Subshell cd wrapping: Wrapping Python calls in (cd "$DOCS_PATH" && python3 ...) is the right shell-side fix for the cwd issue.
• Dynamic path counts: Replacing hardcoded 573 with runtime lookups from the manifest is correct — that number drifts constantly.
• Test self-sufficiency: Making test_no_deprecated_paths and test_internal_links_in_manifest not silently skip is a meaningful improvement.

---

Issues

1. Plan documents expose local dev paths (should not be committed)

The three new files under docs/plans/ contain hardcoded local development paths:

cd /home/rudycosta3/claude-code-docs

These are implementation planning artifacts intended for the development workflow, not public documentation. Committing them to the repo:

• Exposes the developer's local username and machine path
• Adds noise to the docs/ directory that users will encounter
• The Phase 2 plan is for future work not included in this PR

Recommendation: Move these to a private location, a CHANGELOG entry, or simply drop them. A PR description already captures the "what and why" without needing to commit the planning scratchpad.

---

2. update_all_docs() in helper script still missing the cd fix

Three Python calls are correctly wrapped in (cd "$DOCS_PATH" && ...), but the update_all_docs function's main.py call is not:

# Still un-wrapped in the patched file:
if python3 "$SCRIPTS_PATH/main.py" --update-all 2>/dev/null; then

If main.py uses any relative paths internally (same pattern as search.py before this fix), calling it without cd will break from a different working directory. Suggest wrapping it:

if (cd "$DOCS_PATH" && python3 "$SCRIPTS_PATH/main.py" --update-all) 2>/dev/null; then

---

3. test_python_calls_use_subshell_cd assertion is too broad

assert 'cd' in call, (...)

This checks for the substring 'cd' anywhere in the line. A path like lookup_paths.py --search-cd-stuff or a variable name containing cd would satisfy it. Better to assert the specific subshell pattern:

import re
assert re.search(r'\(cd\s+', call), (
    f"Python call must use '(cd ...' subshell pattern: {call}"
)

---

4. Behavioral test missing for the actual cwd bug

test_load_search_index_uses_script_relative_path validates the implementation by inspecting source code for the absence of a string. This is brittle — it fails to catch alternative wrong implementations (e.g., someone writes Path('docs' + '/.search_index.json')).

A more robust complement would be a behavioral test:

def test_load_search_index_path_is_absolute(self, tmp_path, monkeypatch):
    """load_search_index should work regardless of current working directory."""
    monkeypatch.chdir(tmp_path)  # Change cwd to temp dir (no docs/ here)

    from lookup.search import load_search_index
    load_search_index.cache_clear()

    # Should return None (no index at tmp_path/docs/.search_index.json)
    # rather than raising FileNotFoundError or similar
    result = load_search_index()
    assert result is None  # Gracefully returns None, does not crash

This tests the behavior (graceful handling regardless of cwd) rather than the implementation detail (string not present in source).

---

5. Minor: continue-on-error: true on search index build silently swallows failures

- name: Build search index
  if: steps.validate-safeguard.outputs.safeguard_triggered != 'true'
  continue-on-error: true
  run: |
    python3 scripts/build_search_index.py

If build_search_index.py fails, CI silently succeeds and users get a stale/missing search index. Consider making the failure visible even if non-blocking:

    python3 scripts/build_search_index.py || echo "Search index build failed — content search may be unavailable"

---

Summary

Category	Status
Bug fixes (manifest, search path, cd wrapping)	Correct
CI/CD python3 consistency	Good
Test self-sufficiency improvements	Good
Plan docs with local paths in public repo	Should remove
update_all_docs missing cd wrap	Inconsistency
test_python_calls_use_subshell_cd assertion	Could be stronger
Behavioral test for cwd fix	Nice to have

The three real bugs being fixed are legitimate and the fixes are correct. The plan document concern is the most important thing to address before merge — the rest are polish items. Good work overall.

[costiash]

Review Round 2 — All Items Addressed

All 5 items from the second review have been resolved in commit 2674520.

#	Item	Resolution
1	Plan docs with local paths	Untracked from git, added docs/plans/ to .gitignore. Files remain locally for ongoing work.
2	update_all_docs() missing cd wrap	Wrapped both main.py and build_search_index.py calls in (cd "$DOCS_PATH" && ...) subshells.
3	Test assertion too broad	Replaced 'cd' in call with re.search(r'\(cd\s+', call) to match the actual subshell pattern.
4	Behavioral test for cwd bug	Added test_load_search_index_works_from_different_cwd. Note: the suggested assertion (assert result is None) was incorrect — the __file__-relative fix means the function correctly resolves the real index regardless of cwd, so it returns data, not None. The test verifies no crash and valid data structure.
5	Silent failure swallowing	Added `

Verification

• Full test suite: 303 passed, 0 failed (1 new test added)
• All modified files confirmed via grep/ls

Branch Status

This branch is complete. Both review rounds (10 items total) have been addressed. The PR is ready to merge — no further changes planned.

[claude]

PR Review: fix: CI/CD robustness, search path resolution, and test self-sufficiency

Overall this is a well-focused, coherent set of bug fixes. The changes are well-scoped and come with good test coverage. A few observations below.

---

✅ Strengths

Search path fix (scripts/lookup/search.py) — The __file__-relative resolution is the correct approach:

repo_root = Path(__file__).resolve().parent.parent.parent
index_file = repo_root / "docs" / ".search_index.json"

The depth is correct (search.py is at scripts/lookup/search.py — three levels up reaches repo root). This is a proper fix for issue #15.

python3 -m pip across all workflows — Using the module form prevents the wrong interpreter being used when multiple Python versions coexist. Good hygiene.

Staging paths_manifest.json in CI — The previous git add -A docs/ was a silent bug: manifest changes were never committed. Adding paths_manifest.json to the git add command is the right fix.

Test improvements — Converting previously-skipped tests to self-sufficient ones is the right call. The new tests are meaningful rather than passing vacuously.

---

⚠️ Issues / Suggestions

1. lru_cache on load_search_index will cache None on fresh clone

If load_search_index() is called before the search index exists (e.g., fresh clone before the first update_all_docs() run), it caches None. The index will remain None for the lifetime of the process even if build_search_index.py runs later. This was a pre-existing issue, but the PR's focus on load_search_index makes it worth addressing now:

# The None return gets cached; index built later in the same process is never seen
@lru_cache(maxsize=1)
def load_search_index() -> Optional[Dict]:
    repo_root = Path(__file__).resolve().parent.parent.parent
    index_file = repo_root / "docs" / ".search_index.json"
    if not index_file.exists():
        return None  # ← cached forever

One option: skip caching when the result is None, e.g. by using a sentinel and a wrapper, or simply not caching the miss case.

2. Search index step uses continue-on-error: true with no alerting

- name: Build search index
  if: steps.validate-safeguard.outputs.safeguard_triggered \!= 'true'
  continue-on-error: true
  run: |
    python3 scripts/build_search_index.py || echo "Warning: Search index build failed"

continue-on-error: true is fine for not blocking the commit, but a failure will go unnoticed in the step's success status. Consider emitting a GitHub Actions warning annotation (echo "::warning::Search index build failed") to surface failures more visibly in the Actions UI.

3. sys.path.insert at module level in test file

In tests/unit/test_manifest_validation.py:

sys.path.insert(0, str(Path(__file__).parent.parent.parent / "scripts"))
from fetcher.paths import url_to_safe_filename

This path manipulation at module level can interfere with other test modules if any other module named fetcher or lookup exists elsewhere on the path. It's worth checking whether the project's conftest.py already handles this path setup — if so, this sys.path.insert is redundant.

4. 20% orphan tolerance in test_no_deprecated_paths could mask real drift

The tolerance is reasonable in the abstract, but with 573 paths, 20% means up to ~114 orphaned paths before the test fails. Since the PR description mentions some paths are HTML-only or redirect-only, it would strengthen the test to document which paths are known to be unfetchable (or count them separately), so the 20% threshold has a principled basis rather than being an arbitrary ceiling.

5. README.md still has stale per-category counts

The PR correctly removes the total (573/571), but per-category breakdowns remain hardcoded:

- API Reference (377 paths, 65.8%)
- Core Documentation (82 paths, 14.3%)
- Prompt Library (65 paths, 11.3%)
- Claude Code (46 paths, 8.0%)

These will drift whenever a sync adds/removes paths. Out of scope for this PR, but worth a follow-up issue.

6. Minor: TARGET_DOCS="" in install.sh leaves dead code

TARGET_DOCS is never actually assigned at runtime after being set to "". It's referenced in the upgrade summary block but now effectively prints nothing for the doc count. Consider computing it dynamically after install (e.g., counting installed .md files) or removing the variable entirely to avoid confusion.

---

Minor Nits

• The test test_python_calls_use_subshell_cd checks re.search(r'\(cd\s+', call) — this is fine for the current implementation but somewhat brittle if the pattern changes slightly. A comment documenting the invariant being enforced would help future maintainers.
• CONTRIBUTING.md had 629 tests (clearly a stale typo) — good catch fixing that to 302.

---

Summary

Area	Assessment
Core bug fix (search path)	✅ Correct and well-tested
CI python3 consistency	✅ Good practice
Manifest staging in CI	✅ Real bug fix
Search index in CI pipeline	✅ Correct, minor monitoring gap
Test self-sufficiency	✅ Meaningful improvement
Hardcoded count removal	✅ Future-proofs the docs
lru_cache None caching	⚠️ Pre-existing issue worth addressing
sys.path.insert in tests	⚠️ Low risk but worth cleaning up

This is ready to merge with the minor caveats noted. The lru_cache None-caching issue is the only one with a real user-visible impact (content search silently not working on fresh installs until process restart) and would be worth a quick follow-up.

[costiash]

Final Update — Branch Complete

Commit dcb529b addresses the last item worth fixing and wraps up this branch.

What changed

TARGET_DOCS fix (install.sh): The variable was declared empty with a "determined at runtime" comment, but nothing computed it. Upgrading users saw After: v0.5.1 ( documentation files) — blank where the count should be. Now set from DOC_COUNT after verification, with ${DOC_COUNT:-0} fallback for the edge case where docs/ is missing.

README.md rewrite: Cut from 452 lines to ~120. Removed hardcoded per-category counts (the drift problem noted in item 5), stale v0.4.x upgrade guide, redundant architecture tree (duplicates CLAUDE.md/CONTRIBUTING.md), verbose 30-line examples section, and over-detailed security internals. The README now focuses on what users need: install, use, update, troubleshoot.

Test counts: Updated 302 → 303 across CLAUDE.md and CONTRIBUTING.md to reflect the new behavioral test.

Remaining review items — not implementing

Item	Reason
lru_cache caching None	Pre-existing, out of scope. Each CLI invocation is a new process — the cache lifetime is one command. The "build index then search in same process" scenario doesn't happen in real usage.
::warning:: GitHub annotation	The continue-on-error: true already marks failed steps with an orange icon in the Actions UI. The || echo fallback surfaces it in logs. Adding ::warning:: is a cosmetic preference, not a functional gap.
sys.path.insert in tests	Established pattern used across 11+ test files. Changing it is a separate refactor with its own test implications.
20% orphan tolerance documentation	The threshold works correctly and was validated in review round 1. Documenting "why 20%" is polish.
Regex comment in test	The test has a docstring and inline comment. A 3-line test body doesn't need more documentation.

Verification

• 303 passed, 0 failed (fresh run)
• install.sh syntax check: OK
• All modified files confirmed

This is the last commit for this PR. Ready to merge.

[claude]

PR Review: CI/CD robustness, search path resolution, and test self-sufficiency

Overall this is a well-scoped, focused set of bug fixes. The changes are coherent and address real issues. Below are observations per area.

---

CI/CD Workflows

python3 -m pip instead of pip — correct fix. Using python3 -m pip ensures pip installs into the active Python 3 environment and avoids any system-level pip/pip2 confusion.

Staging paths_manifest.json — important fix. Previously the manifest was regenerated on each fetch but never committed since only docs/ was staged. The new git add -A docs/ paths_manifest.json correctly captures both.

Build search index step — the sequence is correct: build index → git add -A docs/ (picks up docs/.search_index.json) → commit. The continue-on-error: true is acceptable here since a missing index degrades gracefully.

---

scripts/lookup/search.py — __file__-relative path

Before (cwd-dependent):

index_file = Path("docs/.search_index.json")

After:

repo_root = Path(__file__).resolve().parent.parent.parent
index_file = repo_root / "docs" / ".search_index.json"

Correct fix for issue #15. One note: the parent.parent.parent chain implicitly assumes scripts/lookup/search.py is always exactly 3 levels below the repo root. A short comment stating the expected structure (repo_root/scripts/lookup/search.py) would help future maintainers avoid silent miscalculation if the file is ever moved.

---

scripts/claude-docs-helper.sh — subshell cd wrapping

The (cd "$DOCS_PATH" && python3 ...) pattern is the right approach. It avoids mutating the parent shell's working directory while ensuring each Python call runs with the correct cwd.

Minor gap: test_python_calls_use_subshell_cd only validates calls containing lookup_paths.py. Calls to main.py and build_search_index.py are also wrapped correctly, but aren't covered by the test. Not a blocker, but worth expanding if those scripts ever develop cwd-dependent path resolution.

---

Tests — Self-sufficiency

test_no_deprecated_paths: Using url_to_safe_filename() from the production fetcher is exactly right — the test now validates against the same logic used to generate filenames, so they stay in sync automatically. The 20% orphan tolerance is pragmatic (some paths are legitimately unfetchable: HTML-only pages, SDK language variants, etc.). The first-10-orphans message in the assertion makes failures actionable.

test_internal_links_in_manifest: The rewrite is a significant improvement — scanning real docs instead of relying on a potentially-missing fixture. The > 100 total_links sanity check is smart; it ensures the regex is actually matching rather than silently passing on an empty result. The 30% tolerance with console output of the actual percentage is good for CI visibility.

inspect.getsource() instead of __wrapped__: Correct. __wrapped__ is not guaranteed to exist on all decorated functions; inspect.getsource() works regardless of decorator stack.

---

Minor Observations

1. test_helper_no_hardcoded_path_counts checks specifically for the string "573". If a future commit introduces a different hardcoded count (e.g., "Searching 600 paths"), this test won't catch it. A broader regex like r'[Ss]earching \d+ ' would be more durable. Not a blocker.

2. TARGET_DOCS flow in install.sh: Initializing TARGET_DOCS="" at the top and assigning it from DOC_COUNT after verification is correct — the only use of TARGET_DOCS is in the post-install upgrade summary block, which runs after verification. The earlier show_upgrade_info() call no longer references it. Clean.

3. README reduction: The trimming is defensible — the removed sections were partially outdated (e.g., still referenced "294 passed, 2 skipped"). The leaner README is easier to keep accurate.

---

Summary

Area	Assessment
CI/CD python3 consistency	Correct fix
Staging paths_manifest.json	Correct fix
Search index build in CI	Correct; sequencing is right
search.py __file__-relative path	Correct fix for #15
Helper script cd subshells	Correct pattern
test_no_deprecated_paths	Self-sufficient now
test_internal_links_in_manifest	Substantial improvement
inspect.getsource()	More robust than __wrapped__
Test coverage gap (main.py/build_search_index.py)	Minor, not a blocker
Hardcoded-count test specificity	Minor, not a blocker

The fixes are correct and the test improvements address real validation gaps. The minor observations are worth noting for follow-up but don't block merging.