## Summary - Align English and Chinese documentation for Docker/Compose, sandbox execution, and the in-tree tracing API with verified runtime behavior. - Separate proactivity usage guidance from developer design and implementation details, with configuration, troubleshooting, cost, and safety boundaries. - Update navigation and remove redundant section separators. Keep page URLs unchanged. - Preserve published proactivity section and title anchors in both languages. Use native aliases for same-page content and visible migration links for moved sections, with regression tests. - Clarify Sentinel delivery fallback and menu-selection requirements, tracing-on/off argument handling, headless CLI menu output, and viewer descriptor lookup. Add focused regression coverage without changing runtime behavior. - Clarify the initial frozen baseline and improve Evolver wording in the bilingual site and repository mapping. Keep its structure, navigation, implementation terms, and technical claims unchanged; broader Evolver documentation work is excluded. - No runtime changes. ## Type - [ ] Fix - [ ] Feature - [x] Docs - [ ] CI / tooling - [ ] Refactor - [ ] Other ## Verification Passed on the rebased revision: ```bash uv run --frozen --no-sync pytest tests/test_docs_site.py tests/test_tracing_api.py tests/test_sandbox_unit.py tests/test_sentinel_runner.py tests/test_sentinel_planner.py tests/test_sentinel_fast_path.py tests/test_nudge_policy.py tests/test_proactive_spawn.py tests/test_core_sentinel_stack.py tests/test_core_cron_stack_ledger.py tests/test_cli_sentinel_commands.py tests/test_decision_router.py -q -n 0 -x # 395 passed uv run --frozen --no-sync --with 'mkdocs-material>=9.5' --with 'mkdocs-static-i18n>=1.0' --with 'mkdocs-git-revision-date-localized-plugin>=1.6.0' --with 'jieba>=0.42.1' mkdocs build -f docs-site/mkdocs.yml --strict --site-dir /tmp/raven-pr551-push.9ZfOEi/site # Strict English and Chinese builds passed UV_NO_SYNC=1 make lint-python PYTHON_LINT_TARGETS='tests/test_docs_site.py tests/test_tracing_api.py tests/test_decision_router.py tests/test_cli_sentinel_commands.py' UV_NO_SYNC=1 make check-large-files check-source-language COMMIT_RANGE=origin/main..HEAD PYTHONPATH=. uv run --frozen --no-sync python scripts/check_commit_messages.py origin/main..HEAD npm exec --yes --package=@commitlint/cli@21.1.0 -- commitlint --from origin/main --to HEAD --config commitlint.config.cjs git diff --check origin/main...HEAD # All passed ``` - [x] Relevant tests pass locally - [x] Relevant lint / type checks pass locally - [x] User-facing docs or screenshots are updated when needed Documentation checks also covered bilingual examples and the proactivity JSON configuration schema. A built-HTML audit verified all 110 historical proactivity section fragments and four title fragments, including same-language migration destinations, and found zero broken internal fragment links across 29 HTML pages (672 links). Replaying pre-fix content made all four page compatibility cases fail as expected. The new descriptor-directory test failed on all three documents before their stale paths were corrected. Added coverage exercises tracing on/off, bare-number versus explicit menu selection with incomplete classifier configuration, and discovery-menu dispatch through the real CLI stack's headless sink. Runtime type checks and the full repository test suite were not run; no runtime code changes. No browser click test, live LLM, real-VM, or container end-to-end run was performed. ## Risk Documentation-only, with regression tests. Proactivity navigation changes, but page URLs and historical heading fragments are preserved. An old link to content moved between pages lands on a visible migration entry and requires one click to reach the new section; no JavaScript redirect is needed. Existing queued-nudge policy and external-agent isolation limitations are described, not fixed. Roll back by reverting the documentation and associated test changes; no data migration is involved. - [x] Security impact considered - [x] Backward compatibility considered - [x] Rollback path is clear for risky changes ## Related Issues N/A --------- Co-authored-by: zhao.wang <270284818+userName20260323@users.noreply.github.com> Co-authored-by: Codex <noreply@openai.com>
275 lines
12 KiB
Python
275 lines
12 KiB
Python
"""The documentation site's pages keep the three properties a broken move costs.
|
|
|
|
A repository-relative link in a .md page is already caught by mkdocs build
|
|
--strict; this guard catches non-.md targets (e.g., docker/.env) that --strict
|
|
misses, and runs in the ordinary test suite without needing the docs uv group.
|
|
A page added in one language only leaves the other language's reader on a
|
|
fallback they cannot tell from a translation. A brand class names a rule in a
|
|
stylesheet no build step connects it to, so renaming either side errors
|
|
nowhere, reddens nothing, and is visible only to someone looking at the page.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import re
|
|
import xml.etree.ElementTree as ET
|
|
from pathlib import Path
|
|
|
|
import pytest
|
|
from markdown import markdown
|
|
from markdown.extensions.toc import slugify
|
|
|
|
REPO = Path(__file__).resolve().parent.parent
|
|
SITE = REPO / "docs-site" / "docs"
|
|
STYLESHEET = SITE / "stylesheets" / "evermind.css"
|
|
|
|
LINK = re.compile(r"\[[^\]]*\]\(([^)]+)\)")
|
|
HEADING = re.compile(r"^(#{2,6})\s+(.+?)\s*$", re.M)
|
|
ANCHOR = re.compile(r"\{\s*#([\w-]+)\s*\}")
|
|
CLASS_ATTR = re.compile(r'class="([^"]*)"')
|
|
CSS_SELECTOR = re.compile(r"\.(em-[a-z][a-z0-9-]*)")
|
|
|
|
# Published fragments are a compatibility contract, independent of current headings.
|
|
PROACTIVITY_LEGACY_SECTIONS = {
|
|
"proactivity": {
|
|
"proactivity-design.md#components-and-assembly": ("architecture-overview",),
|
|
"proactivity-design.md#context-and-decision-contracts": (
|
|
"1-data-types-sentineltypespy",
|
|
"plannerdecision",
|
|
"plannercontext",
|
|
"3-context-assembly-contextassembler-sentinelpredictorcontext_assemblerpy",
|
|
"4-decision-layer-proactiveplanner-sentinelplannerpy",
|
|
),
|
|
"proactivity-design.md#tick-lifecycle": (
|
|
"2-orchestration-sentinelrunner-sentinelexecutorrunnerpy",
|
|
"one-tick",
|
|
"fast-path-rules-skip-only",
|
|
"scheduled-fire-fast-path",
|
|
"drive-modes",
|
|
"tickoutcome",
|
|
),
|
|
"proactivity-design.md#action-routing": (
|
|
"action",
|
|
"degradation",
|
|
"6-the-three-nudge-execution-paths",
|
|
"nudgedispatcher-sentinelexecutordispatcherpy",
|
|
"nudgeinjector-sentinelexecutorinjectorpy",
|
|
"defermanager-sentinelexecutordefer_managerpy",
|
|
"7-the-spawn_agent-path-proactivespawn-sentinelexecutorspawnpy",
|
|
),
|
|
"proactivity-design.md#policy-boundaries": (
|
|
"5-the-gate-nudgepolicy-sentineltrigger_policypolicypy",
|
|
"layered-checks",
|
|
"adaptive-multiplier",
|
|
"readwrite-split",
|
|
"personalization-and-persistence",
|
|
),
|
|
"proactivity-design.md#state-and-feedback": (
|
|
"8-feedback-loop-nudgefeedbacktracker-the-nudge-feedback-tool",
|
|
"9-state-files",
|
|
),
|
|
"proactivity-design.md#routines-and-task-discovery": ("12-task-discovery-anticipatory-menus",),
|
|
"proactivity-design.md#cron-heartbeat-and-the-spine": (
|
|
"10-cron-schedulerscron",
|
|
"11-heartbeat-and-event-driven-wake",
|
|
"13-spine-integration-and-the-user-inbound-gates",
|
|
"mid-turn-user-input-busypolicyinject",
|
|
"ask_user-pausing-a-turn-to-ask-the-user",
|
|
),
|
|
},
|
|
"proactivity-design": {
|
|
"#design-rationale": (
|
|
"1-three-layers-of-proactivity",
|
|
"2-the-core-idea-periodic-planner-plus-on-demand-spawn",
|
|
"7-scenarios",
|
|
"l2-routine-automation",
|
|
"l3-memory-linked-reminder",
|
|
"l3-context-aware-resumption",
|
|
"l3-proactive-status-check",
|
|
),
|
|
"#components-and-assembly": ("3-components",),
|
|
"#context-and-decision-contracts": (
|
|
"proactiveplanner-periodic-reasoner",
|
|
"contextassembler-input-packaging",
|
|
"planner-decision-quality",
|
|
),
|
|
"#action-routing": (
|
|
"4-action-space",
|
|
"proactivespawn-multi-step-execution-bridge",
|
|
),
|
|
"#policy-boundaries": (
|
|
"nudgepolicy-the-shared-anti-spam-gate",
|
|
"5-anti-spam-the-nudgepolicy-gate",
|
|
"9-risks-and-mitigations",
|
|
"over-notification",
|
|
),
|
|
"#routines-and-task-discovery": (
|
|
"routinelearner-behavior-pattern-learning",
|
|
"task-discovery-anticipatory-menus",
|
|
"history-format-drift",
|
|
),
|
|
"#cron-heartbeat-and-the-spine": ("6-delivery-and-turn-transport-the-spine",),
|
|
"proactivity.md#costs-and-safety-limits": ("8-cost", "spawn-safety"),
|
|
},
|
|
}
|
|
|
|
|
|
def _pages() -> list[Path]:
|
|
return sorted(SITE.glob("*.md"))
|
|
|
|
|
|
def test_every_page_has_both_languages() -> None:
|
|
english = {path.stem for path in _pages() if not path.name.endswith(".zh.md")}
|
|
chinese = {path.name[: -len(".zh.md")] for path in _pages() if path.name.endswith(".zh.md")}
|
|
|
|
assert english == chinese, (
|
|
f"English page without a Chinese twin: {sorted(english - chinese)}; "
|
|
f"Chinese page without an English twin: {sorted(chinese - english)}"
|
|
)
|
|
assert english, "no pages found -- did SITE move?"
|
|
|
|
|
|
def test_no_page_links_into_the_repository_by_a_relative_path() -> None:
|
|
pages = _pages()
|
|
assert pages, "no pages found -- did SITE move?"
|
|
offenders: list[str] = []
|
|
for page in pages:
|
|
for target in LINK.findall(page.read_text(encoding="utf-8")):
|
|
link = target.split("#", 1)[0].split(" ", 1)[0]
|
|
if not link or link.startswith(("http://", "https://", "mailto:")):
|
|
continue
|
|
if "/" not in link and link.endswith(".md"):
|
|
continue
|
|
offenders.append(f"{page.name} -> {target}")
|
|
|
|
assert not offenders, (
|
|
"repository-relative links in non-.md targets are not caught by mkdocs "
|
|
"build --strict; make them absolute github.com URLs: "
|
|
f"{offenders}"
|
|
)
|
|
|
|
|
|
def test_pages_do_not_link_to_external_webpages() -> None:
|
|
offenders: list[str] = []
|
|
for page in _pages():
|
|
for target in LINK.findall(page.read_text(encoding="utf-8")):
|
|
if target.startswith(("http://", "https://")):
|
|
offenders.append(f"{page.name} -> {target}")
|
|
|
|
assert not offenders, f"site pages must keep documentation links internal: {offenders}"
|
|
|
|
|
|
def test_brand_classes_used_by_a_page_are_the_ones_the_stylesheet_defines() -> None:
|
|
used: set[str] = set()
|
|
for page in _pages():
|
|
for attr in CLASS_ATTR.findall(page.read_text(encoding="utf-8")):
|
|
used |= {name for name in attr.split() if name.startswith("em-")}
|
|
defined = set(CSS_SELECTOR.findall(STYLESHEET.read_text(encoding="utf-8")))
|
|
|
|
assert used, "no em-* class found on any page -- did the brand markup move?"
|
|
assert used == defined, (
|
|
f"class used by a page with no rule to style it: {sorted(used - defined)}; "
|
|
f"rule no page reaches: {sorted(defined - used)}"
|
|
)
|
|
|
|
|
|
def _headings(text: str) -> list[tuple[int, str, str]]:
|
|
"""Every heading below the title, with the anchor it will render with."""
|
|
found = []
|
|
for hashes, raw in HEADING.findall(text):
|
|
pinned = ANCHOR.search(raw)
|
|
title = re.sub(r"<[^>]+>", "", ANCHOR.sub("", raw)).strip()
|
|
found.append((len(hashes), title, pinned.group(1) if pinned else slugify(title, "-")))
|
|
return found
|
|
|
|
|
|
def test_chinese_headings_pin_the_anchor_their_english_twin_gets_for_free() -> None:
|
|
"""A CJK heading slugifies to nothing, so Markdown numbers it `_1`, `_2`, ...
|
|
|
|
Those anchors are positional: inserting one heading renumbers every anchor
|
|
below it, silently breaking the links other pages and outside readers hold.
|
|
An English title slugifies on its own, so the Chinese page has to say the
|
|
same anchor out loud for the two to stay reachable by one link.
|
|
"""
|
|
offenders: list[str] = []
|
|
for english in sorted(page for page in _pages() if not page.name.endswith(".zh.md")):
|
|
chinese = english.with_name(f"{english.stem}.zh.md")
|
|
if not chinese.exists():
|
|
continue
|
|
left = _headings(english.read_text(encoding="utf-8"))
|
|
right = _headings(chinese.read_text(encoding="utf-8"))
|
|
if [depth for depth, _, _ in left] != [depth for depth, _, _ in right]:
|
|
offenders.append(
|
|
f"{english.stem}: heading levels differ, {[d for d, _, _ in left]} vs {[d for d, _, _ in right]}"
|
|
)
|
|
continue
|
|
for (_, en_title, en_anchor), (_, zh_title, zh_anchor) in zip(left, right):
|
|
if not zh_anchor:
|
|
offenders.append(f"{chinese.name}: {zh_title!r} has no anchor, so Markdown will number it")
|
|
elif zh_anchor != en_anchor:
|
|
offenders.append(
|
|
f"{chinese.name}: {zh_title!r} lands on #{zh_anchor}, but {en_title!r} lands on #{en_anchor}"
|
|
)
|
|
|
|
assert not offenders, "\n".join(offenders)
|
|
|
|
|
|
def _render_page(name: str) -> ET.Element:
|
|
html = markdown(
|
|
(SITE / name).read_text(encoding="utf-8"),
|
|
extensions=["admonition", "attr_list", "md_in_html", "tables", "toc", "fenced_code"],
|
|
)
|
|
return ET.fromstring(f"<article>{html}</article>")
|
|
|
|
|
|
@pytest.mark.parametrize("language", ["", ".zh"])
|
|
@pytest.mark.parametrize("page", PROACTIVITY_LEGACY_SECTIONS)
|
|
def test_proactivity_legacy_sections_reach_current_content(page: str, language: str) -> None:
|
|
root = _render_page(f"{page}{language}.md")
|
|
elements = list(root.iter())
|
|
ids = [element.attrib["id"] for element in elements if "id" in element.attrib]
|
|
assert len(ids) == len(set(ids)), f"duplicate IDs in {page}{language}"
|
|
by_id = {element.attrib["id"]: element for element in elements if "id" in element.attrib}
|
|
parents = {child: parent for parent in elements for child in parent}
|
|
|
|
for target, legacy_ids in PROACTIVITY_LEGACY_SECTIONS[page].items():
|
|
target_page, target_id = target.split("#")
|
|
destination = _render_page(f"{Path(target_page).stem}{language}.md") if target_page else root
|
|
assert any(element.get("id") == target_id for element in destination.iter("h2")), target
|
|
|
|
for legacy_id in legacy_ids:
|
|
assert legacy_id in by_id, f"{page}{language}.md lost #{legacy_id}"
|
|
anchor = by_id[legacy_id]
|
|
if target_page:
|
|
container = parents[anchor]
|
|
assert container.tag in {"li", "p"}, f"#{legacy_id} has no visible migration entry"
|
|
assert any(
|
|
link.get("href") == target and "".join(link.itertext()).strip() for link in container.iter("a")
|
|
), f"#{legacy_id} has no migration link to {target}"
|
|
else:
|
|
next_heading = next(
|
|
element for element in elements[elements.index(anchor) + 1 :] if element.tag == "h2"
|
|
)
|
|
assert next_heading.get("id") == target_id, f"#{legacy_id} lands before the wrong section"
|
|
|
|
|
|
@pytest.mark.parametrize("language", ["", ".zh"])
|
|
@pytest.mark.parametrize("page", PROACTIVITY_LEGACY_SECTIONS)
|
|
def test_proactivity_preserves_published_title_anchors(page: str, language: str) -> None:
|
|
title_id = "_1" if language else "proactivity-reference" if page == "proactivity" else page
|
|
root = _render_page(f"{page}{language}.md")
|
|
assert root.find(f"h1[@id='{title_id}']") is not None
|
|
|
|
|
|
@pytest.mark.parametrize(
|
|
"document",
|
|
[SITE / "tracing-api.md", SITE / "tracing-api.zh.md", REPO / "docs" / "TRACING_STANDARD_API.md"],
|
|
)
|
|
def test_tracing_descriptor_documentation_points_to_bundled_files(document: Path) -> None:
|
|
paths = re.findall(r"`([^`\n]+/descriptors/)`", document.read_text(encoding="utf-8"))
|
|
assert paths, f"{document.name} does not name the bundled descriptor directory"
|
|
for path in paths:
|
|
directory = REPO / path
|
|
assert directory.is_dir(), f"{document.name} points to missing directory {path}"
|
|
assert any(directory.glob("*.json")), f"{path} has no bundled JSON descriptors"
|