Quality, config containment, and readability coverage pass

[jrepp]

Summary

• Enforce docs-project path containment for docs roots, document folders, subproject references, and index target paths unless security.allow_external_paths: true is explicitly enabled.
• Support loading docs/docs-project.yaml for projects rooted under ./docs.
• Optimize subproject config traversal by replacing queue-style list.pop(0) loops with deque.popleft() in CLI and validator paths.
• Tighten bulk frontmatter update validation so empty field names and empty rename targets fail with clear errors.
• Refactor readability paragraph extraction to share paragraph flushing logic and fix standalone HTML lines such as <br> swallowing the next paragraph.
• Add coverage for config containment, readability paragraph extraction, bulk update validation, and related schema/template behavior.

Measurements

Measured locally with synthetic before/after equivalents after the optimization pass.

Subproject traversal, list.pop(0) baseline vs deque.popleft() current:

Synthetic graph size	Baseline list	Current deque	Result
10 nodes	0.85 us	0.89 us	0.95x
100 nodes	8.63 us	7.08 us	1.22x faster
1,000 nodes	124.10 us	84.70 us	1.47x faster
5,000 nodes	1296.10 us	391.78 us	3.31x faster

Readability extraction refactor, same-behavior benchmark without standalone HTML behavior differences:

Paragraph count	Baseline	Current	Result
50	0.040 ms	0.045 ms	0.89x
500	0.412 ms	0.446 ms	0.93x
2,000	1.618 ms	1.769 ms	0.92x

Interpretation: the deque traversal change is a measurable optimization for larger subproject graphs. The readability refactor is primarily a correctness and maintainability change, not a runtime optimization; it intentionally fixes dropped paragraphs after standalone HTML tags.

Validation

• uv run pytest (677 passed)
• uv run ruff check docuchango tests
• uv run mypy docuchango/cli.py docuchango/validator.py docuchango/readability.py docuchango/fixes/bulk_update.py
• uv run pytest --cov=docuchango --cov-report=term-missing (677 passed, total coverage 72.68%)

Notes

Historical multi-project layouts should use subprojects from a parent config. security.allow_external_paths: true remains available as an explicit escape hatch for trusted legacy layouts.