Docs Hub sprint-3 closure + dashboard sticky TOC#58
Merged
Conversation
…+ E + cleanup) Closure sprint of the Docs Hub effort. Scope: LanceDB ingest of docs/, cross-link audit, delete docs/INDEX.md, fix sys.modules test hazard. All four are Sprint 2 carry-overs. Scope ceiling: 8 files, 120 LOC production, 300 LOC tests, 0 new deps. Implementation order is revert-able step-by-step. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…ys.modules with reload + setattr The old helper used `del sys.modules[mod_name]` + re-import, creating a new module object. arail.portal.app._docs_registry kept the old object, so patches applied via the helper were invisible to app routes — the F5 carry-over flake from TEST_REPORT.md. Fix: - _fresh_registry now calls importlib.reload() on the existing module object (preserving identity) then patches _repo_root and _docs_registry on app.py via monkeypatch.setattr for proper teardown. - test_live_repo_* tests switch from del sys.modules to importlib.reload for the same reason — they were the contamination source that caused the ordering-dependent failures. - New test: test_fresh_registry_rebinds_app_module_reference pins the fix. All 126 docs test pass together (125 pre-existing + 1 new). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds a slim sticky strip below the meter bar with six anchor chips — Mission · Status · Activity · Report · Knowledge · Network — that smooth-scroll to each card. Quick Actions stays where it is (those are real verbs, not nav). - Invisible .dash-anchor spans placed just above each card carry the #dash-* targets so we don't have to repurpose existing card ids. - scroll-margin-top: 56px keeps the heading clear of the sticky TOC. - Translucent dark background + backdrop blur so the strip reads as chrome, not a section. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…n.md/wiki.md links New test file tests/test_docs_cross_links.py: - test_cross_link_audit_all_internal_links_resolve: walks the registered docs corpus, strips fenced code blocks, asserts every [label](*.md) link resolves to an existing file (F3, F4). - test_cross_link_audit_allowlist_is_minimal: pins allowlist size ≤10 so unexpected growth surfaces in CI. - test_cross_link_audit_code_fence_false_negative_is_blocked: confirms links inside ``` fences are stripped before the regex sweep (F4). - test_cross_link_audit_real_link_outside_fence_is_caught: positive case. - test_cross_link_audit_perf_under_one_second: full audit < 1s (F10). Broken links fixed (edit the doc, not the allowlist — per architect spec): - docs/build-and-finetune-plan.md: ./design.md → ./portal-design.md - ROADMAP.md: docs/design.md → docs/portal-design.md - CONTRIBUTING.md: docs/wiki.md removed (no wiki.md exists; pointed at /wiki tab) Broken-link count in registered docs: 3 → 0. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…rect + regression tests
- docs/INDEX.md deleted: the legacy Hub placeholder that the denylist
has blocked since Sprint 1. /docs now renders the registry-driven Hub
directly; the file served no purpose on disk.
- app.py: add GET /docs/INDEX.md → 301 /docs permanent redirect handler.
The handler intentionally does NOT read the file — it fires regardless
of whether INDEX.md is on disk, preserving any external bookmarks (F6).
- tests/test_docs_routes.py:
- test_viewer_renders_doc_without_registry_entry: updated from 200
assertion (Sprint 2, file existed) to 301 assertion (Sprint 3, file
deleted). Documents the intent change inline.
- test_docs_index_md_redirect_still_works: primary F6 sentinel — asserts
301 to /docs after file deletion.
- test_index_md_file_does_not_exist: belt-and-suspenders file-gone check
so a future restore is caught immediately.
All 133 docs tests pass.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…des registered docs src/arail/pkb.py: - New helper _build_docs_rows(): iterates docs_registry.all_docs(), builds one LanceDB row per doc with source_kind='docs'. Row schema matches PKB (path/name/vector/mtime/source_kind) so search callers need no changes. Namespaces paths as "docs/<slug>.md" or "root/<slug>.md" to prevent future PKB/docs collisions. Body capped at 4 KB (same as PKB, per F1 perf guard). Registry failures log a warning and return [] — docs ingest never blocks PKB ingest (F8 isolation contract). - index_all() gains include_docs=True kwarg (default preserves prior behaviour). Return dict gains indexed_docs key (0 when include_docs=False or registry empty). tests/test_docs_ingest.py (new, 7 tests): - test_index_all_includes_docs_rows: indexed_docs ≥ 1, source_kind='docs' (contract) - test_index_all_include_docs_false_skips_docs: opt-out works, no docs rows in DB - test_index_all_handles_registry_failure_gracefully: PKB still indexes on failure (F8) - test_index_all_empty_body_doc_does_not_crash: empty body slice '' is safe (F7) - test_index_all_stale_doc_removed_on_reingest: replace() semantics removes stale (F2) - test_index_all_source_kind_docs_does_not_pollute_pkb_source_kind: isolation (F8) - test_index_all_perf_under_2s: synthetic-50 PKB + real-24 docs < 2.0s (F1) Full 140-test docs suite passes. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…plete Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…tests QA findings: 0 FAIL, 2 LOW (mixed-case .MD audit gap pinned; F5 cross-domain test contamination is pre-existing, not introduced by this sprint — recommended session-scoped autouse fixture follow-up). Coverage: LanceDB re-ingest idempotency, 4 KB embedding cap, empty docs/ dir, missing frontmatter, INDEX.md redirect (301 + query string + case variants), 3-way concurrent index_all (no deadlock), cross-link edge cases (anchors, query strings, backticks, mixed-case .MD), sys.modules rebind hermeticity over repeated calls. Closes docs-hub-sprint-3. Ready to ship. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
cdarnell
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Bundles two pieces of work on the same branch:
docs-hub-sprint-3 — closure of the Docs Hub effort
Master plan Phase D + E + cleanup, all four planned steps shipped:
tests/test_docs_registry_qa.py_fresh_registryhelper now rebindsarail.portal.app._docs_registryviamonkeypatch.setattrinstead ofdel sys.modules[...]. Sistertest_live_repo_*helpers fixed in the same commit (F5).tests/test_docs_links.pywalks every[label](path.md)in the docs corpus and asserts it resolves. 3 broken links repaired:docs/build-and-finetune-plan.md→portal-design.mdROADMAP.md→portal-design.mdCONTRIBUTING.md— deaddocs/wiki.mdlink removeddocs/INDEX.md+ permanent 301 redirect to/docsHub (preserves old bookmarks).pkb.index_allnow includes registered docs alongside user notes. 4 KB embedding cap respected; perf test 0.70s (budget 2.0s).Verdicts: REVIEW = PASS · QA = PASS (18 new tests, 158/158 docs-domain green, 0 FAIL).
Ride-along: dashboard sticky TOC
Charles's
5df5725adds a slim sticky strip below the meter bar with six anchor chips (Mission · Status · Activity · Report · Knowledge · Network) that smooth-scroll to each card. Self-contained, harmless, predates the sprint-3 branching.Carry-overs to next sprint
_MD_LINK_REonly matches lowercase.md(re.IGNORECASEfollow-up; pin test landed)docs_routes_qa.pyflakes. Pre-existing (git stashof sprint-3 leaves failures identical). Recommended: session-scoped autouse fixture restoringapp._docs_registryto import-time value after every test.Test plan
pytest tests/test_docs*.py tests/test_docs_links.py tests/test_docs_ingest.py tests/test_docs_sprint3_qa.py→ 158/158 in isolation/docs/INDEX.md→ 301 to/docspkb_index_all— docs are findable🤖 Generated with Claude Code