Add doc-entrypoint freshness check to maintenance sweeps

[marcusglee11]

Parent / control context

• Parent documentation drift-control epic: Spec: make documentation drift control merge-enforced #117
• Related advisory drift sweep issue: Implement advisory documentation drift sweep issue creator #122
• Should run after the entrypoint baseline refresh issue lands.

Goal

Add a low-noise doc-entrypoint freshness check to the existing maintenance sweep system so stale README / onboarding / entry-chain drift is detected without Marcus needing to ask.

Problem

The current sweep suite can detect broad hygiene/drift, but it does not explicitly guard the first-reader entrypoint. README.md can become stale while deeper docs remain updated.

This should be a detector and issue creator, not an auto-editor.

Scope

Extend either inventory-hygiene-sweep or deep-audit-sweep with a named doc-entrypoint check.

Check these surfaces at minimum:

• README.md
• docs/INDEX.md
• docs/11_admin/LIFEOS_STATE.md
• docs/LifeOS_Strategic_Corpus.md
• config/docs/authority_registry.yaml
• optional onboarding manual if created by the baseline issue

Drift signals to detect

• README current-status text contradicts LIFEOS_STATE.md.
• README does not link to docs/INDEX.md and current-state docs.
• Entry chain omits the current canonical target architecture doc.
• Entry chain omits agent guidance for new AI operators.
• README/wiki/corpus presents derived material as canonical authority.
• Authority manifest classifies an entrypoint surface differently than the README implies.
• Entry surfaces have not changed while canonical state/architecture docs changed materially.

Required sweep behavior

• Read-only: do not edit docs.
• If drift is found, open or update one deduped GitHub issue, not one issue per file.
• Use sweep_lib fingerprint/upsert semantics.
• Target issue repo: marcusglee11/lifeos-operational-bus unless implementation chooses to route doc-code issues to marcusglee11/LifeOS with a clear reason.
• Suggested fingerprint target/check:
  • target=lifeos-doc-entrypoint
  • check_id=readme-entrypoint-freshness
• Labels should be existing sweep/documentation labels only; do not use dispatch-triggering lane labels.
• Keep Telegram quiet unless severity is warning+ and new/unlinked.

Non-goals

• Do not auto-edit README or docs.
• Do not close issues automatically.
• Do not treat wiki/corpus as authority.
• Do not inspect the cron scheduler as the source of sweep health.
• Do not create duplicate issues every run.

Acceptance criteria

• Sweep logic can identify the known stale-README class after synthetic fixture or controlled test input.
• Drift finding creates/updates one deduped issue with evidence and next action.
• Clean state produces no issue spam and no noisy Telegram output.
• Sweep prompt/config records the new check explicitly.
• sweep_lib receipt/finding state matches reported output.
• Registry/labels remain consistent with live GitHub labels.

Suggested validation

python3 ~/.hermes/sweep/scripts/dry_run_test.py
python3 ~/.hermes/sweep/scripts/validate_registry_labels.py --json
# plus a focused synthetic fixture test for README-vs-LIFEOS_STATE mismatch

[marcusglee11]

Fresh-context EA advisory review: APPROVE

Scope reviewed:

• doc_steward/entrypoint_freshness_sweep.py
• doc_steward/cli.py
• tests_doc/test_entrypoint_freshness_sweep.py

Findings:

• Dirty dry-run now uses deterministic local fingerprinting and does not import sweep_lib, touch FindingsDB, write receipts, or create GitHub issues.
• dry_run + record_run is rejected at the shared run() boundary, covering both module and doc_steward.cli entrypoints.
• No cron/scheduler/service activation is introduced.
• Live GitHub issue creation remains explicit behind --create-issue and only after sweep_lib reports a new finding.

QA evidence:

• Local targeted tests: 37 passed.
• Changed-file quality gate: passed blocking checks; mypy advisory unavailable locally.
• Hosted CI: Documentation Validation, Quality Gate, Test Suite 3.11, Test Suite 3.12, Validate Artefact Index all passed.

[marcusglee11]

Merged PR #138 with exact-head guard.

Evidence:

• Approved head: b880f52de9dcff997fec3e10b41cbef0a298c079
• Merge commit on origin/main: e58952fbeb216d33afdb70a592aae93f55e8c259
• Hosted CI before merge: Documentation Validation, Quality Gate, Test Suite 3.11, Test Suite 3.12, Validate Artefact Index all passed.
• Fresh-context EA advisory review: APPROVE.
• Readback on origin/main confirms:
  • doc_steward/entrypoint_freshness_sweep.py
  • tests_doc/test_entrypoint_freshness_sweep.py
  • updated doc_steward/cli.py

Note: #125 remains open because recurring sweep activation/operational path decision is still separate from this code merge.