Reserved wiki dirs (manual/jobs) are matched at any depth, silently dropping user pages

[dev-noaman]

Summary

is_reserved_page_path matches RESERVED_WIKI_SOURCE_DIRS (manual, jobs) at any depth, but those directories are only ever created at the wiki root. Any user page under a directory named manual or jobs — at any level — is silently dropped from the index, from health, and from frontmatter rewriting.

Silently is the important part: because health and validate walk with the same iterator, the tool cannot warn about pages it refuses to see.

Impact (real)

In our wiki, almanac/architecture/jobs/ held four committed pages (~29 KB) documenting our background-job subsystem. They were invisible to search and show, and every link pointing at them was reported as a broken link to a non-existent page:

concepts/external-source-cache-pattern -> architecture/jobs/background-job-queue (target does not exist)

The page existed. reindex reported 46 pages (46 files seen) against 50 .md files on disk, with no indication that four were skipped or why.

Two knock-on effects worth noting:

1. sync fails. The post-run validation gate trips on the resulting broken links, so codealmanac sync exits failed with validation failed: 6 issues; first: broken_links: ... and can never succeed while such a directory exists.
2. It invites duplicate pages. The coverage map listed the page as unwritten and health called the link broken — both consistent with "missing". I was one step from writing a second copy of a page that already existed.

Root cause

codealmanac/services/wiki/paths.py:

RESERVED_WIKI_SOURCE_DIRS = frozenset({"manual", "jobs"})

def is_reserved_page_path(almanac_path: Path, path: Path) -> bool:
    ...
    return any(part in RESERVED_WIKI_SOURCE_DIRS for part in relative.parts[:-1])

any(... for part in relative.parts[:-1]) tests every directory component. But the reserved directories are created only at the wiki root:

• services/wiki/service.py:22 — self.manual.install_missing(almanac_path / "manual")
• workflows/build/service.py:115 — manual_root=repository.almanac_path / "manual"

So the predicate is broader than its purpose. page_id_for_path, immediately below in the same file, already reasons positionally (if len(relative.parts) == 1), so top-level-only is the established convention here.

Reproduction

from pathlib import Path
from codealmanac.services.wiki.paths import is_reserved_page_path

ROOT = Path("/wiki/almanac")
is_reserved_page_path(ROOT, ROOT / "manual/intro.md")             # True  - intended
is_reserved_page_path(ROOT, ROOT / "architecture/jobs/queue.md")  # True  - BUG, user page
is_reserved_page_path(ROOT, ROOT / "concepts/deep/jobs/x.md")     # True  - BUG, user page

Suggested fix

Restrict the check to the first directory component:

    directories = relative.parts[:-1]
    return bool(directories) and directories[0] in RESERVED_WIKI_SOURCE_DIRS

Verified against the installed 0.4.7 with these cases:

path	before	after	intended
manual/intro.md	excluded	excluded	excluded
jobs/run.md	excluded	excluded	excluded
architecture/jobs/queue.md	excluded	indexed	indexed
architecture/manual/setup.md	excluded	indexed	indexed
concepts/deep/jobs/nested.md	excluded	indexed	indexed
architecture/risk/overview.md	indexed	indexed	indexed
jobs.md (a file, not a dir)	indexed	indexed	indexed

End-to-end on a real wiki after patching: reindex went from 46 to 50 pages, the four pages became reachable via show, the bundled manual/ stayed excluded, and health went from 6 broken links to 0.

Secondary suggestion

Even with the positional fix, an excluded-by-reservation path is worth surfacing rather than dropping in silence — a health notice such as "N page(s) skipped: reserved directory" would have made this self-diagnosing. As it stands the only symptom is a broken link to a file that visibly exists on disk.

Version: codealmanac 0.4.7, Python 3.13.13, Windows.

[dev-noaman]

Opened #57 with the fix and a regression test.

The test fails on main and passes with the change, so it pins the behaviour rather than just describing it. Nested content inside the bundled manual/ stays excluded, since only the first path component is consulted.

Checks per CONTRIBUTING.md: ruff clean, uv build fine, and the pytest failure set is identical before and after (all pre-existing on this Windows box — 5 are macOS launchd tests).