Implement advisory documentation drift sweep issue creator

[marcusglee11]

Parent epic

• Parent/control issue: Spec: make documentation drift control merge-enforced #117
• Operative spec: Spec: make documentation drift control merge-enforced #117 (comment)
• Review approval: Spec: make documentation drift control merge-enforced #117 (comment)

Goal

Extend recurring maintenance sweeps to detect documentation drift that bypasses or predates the merge path, and open low-noise evidence-backed reconciliation issues.

Sweep should detect

• Missing authority classification.
• Stale wiki/corpus derived surfaces.
• Orphan derived pages.
• Proposal-only/deferred/discarded docs linked as canonical.
• Canonical docs changed without recent reconciliation packet.
• Derived surfaces edited manually without regeneration provenance.

Required behavior

• Open evidence-backed reconciliation issues.
• Deduplicate existing drift issues.
• Never mutate canonical docs.
• Never promote/demote authority classes.
• Keep output actionable and low-noise.

Acceptance criteria

• Sweep can be safely run repeatedly.
• Each created issue includes:
  • exact paths;
  • observed evidence;
  • authority class involved;
  • recommended recovery;
  • link back to parent/control issue Spec: make documentation drift control merge-enforced #117 when applicable.
• Duplicate detection prevents issue spam.
• Sweep is wired into the existing maintenance/meta-sweep surface only after dry-run evidence shows acceptable noise.

Non-goals

• Do not auto-fix docs.
• Do not decide semantic authority disputes.
• Do not promote/deprecate docs automatically.

[marcusglee11]

Entry-point docs follow-up slices

Raised two narrow follow-up issues from the README / operator-entrypoint discussion:

1. Refresh LifeOS operator entrypoint docs #124 — one-off baseline refresh for README/operator entrypoint docs.
2. Add doc-entrypoint freshness check to maintenance sweeps #125 — add low-noise doc-entrypoint freshness detection to maintenance sweeps after the baseline lands.

Sequencing: do #124 first so the sweep has a known-good baseline; then do #125 so future README / entry-chain drift is detected without manual prompting.

[marcusglee11]

Selector advanced to #122 advisory drift sweep

Active work:

• working: yes
• current carrier: LifeOS Implement advisory documentation drift sweep issue creator #122 under parent Tracking: Doc-Drift Merge Gate (#117 + #122 + #125) #141 / ROI queue #1052
• worker/process: EA plan proc_2850c1a8f6d7
• last action: feat: CI-enforced doc drift merge gate (#117/#141) #142 merged and post-merge verified from fresh origin/main; Spec: make documentation drift control merge-enforced #117 substrate dependency satisfied
• next automatic action: review EA plan, implement first dry-run/local Implement advisory documentation drift sweep issue creator #122 slice, parent-verify, independent review, PR/merge if still in envelope
• Marcus needed: no
• stop reason: n/a

First #122 slice scope:

• local/dry-run only
• detect advisory doc drift from checkout/fixtures
• produce issue-preview JSON/markdown with exact paths, evidence, authority class, recommended recovery, parent link, and dedupe fingerprint
• no cron/scheduler activation
• no live GitHub issue creation/comment/close from product code
• no provider/model/credential/runtime/gateway action
• no doc auto-fix or authority promotion/demotion

Workflow lesson: exact-head public merge approval was handled as a real gate; after approval, the queue resumed automatically to the next dependency-safe child.

[marcusglee11]

#122 dry-run advisory drift sweep implementation started

Active work:

• working: yes
• current carrier: LifeOS Implement advisory documentation drift sweep issue creator #122 under Tracking: Doc-Drift Merge Gate (#117 + #122 + #125) #141 / ROI queue #1052
• worker/process: EA implement proc_081177e671af
• last action: EA plan completed; implementation started on branch build/doc-drift-advisory-sweep-122
• next automatic action: parent-verify diff/tests, independent review, AMEND loop if needed, then PR/merge if still in envelope
• Marcus needed: no
• stop reason: n/a

Scope: local/dry-run advisory documentation drift sweep issue preview only. No cron/scheduler activation, no live GitHub issue creation/comment/close from product code, no provider/model calls, no credentials, no runtime/gateway changes, no doc auto-fix, no authority promotion/demotion.

[marcusglee11]

#122 dry-run advisory drift preview PR opened

PR: #143
Head: aa6cf6f7415704367ef6999e0187bf7b9b514fbd

What changed:

• doc_steward/drift_sweep_issue_creator.py — local dry-run issue preview builder with per-class fingerprints and JSON/Markdown output.
• doc_steward.cli drift-sweep-preview — explicit local preview command.
• tests_doc/test_drift_sweep_issue_creator.py — 31 tests covering all six drift classes, clean state, fingerprints, preview shape, safe repeated runs, parent link, and CLI integration.

Local verification:

python3 -m pytest tests_doc/test_drift_sweep_issue_creator.py -q
31 passed

python3 -m pytest tests_doc -q
256 passed, 1 skipped

python3 scripts/workflow/quality_gate.py check --scope changed ... --json
passed=true for blocking checks

python3 -m doc_steward.cli drift-sweep-preview . --output-dir /tmp/doc_drift_preview --json
wrote preview files; clean checkout has 0 findings

EA review: APPROVE

Active work:

• working: yes
• current carrier: LifeOS Implement advisory documentation drift sweep issue creator #122 under Tracking: Doc-Drift Merge Gate (#117 + #122 + #125) #141 / ROI queue #1052
• worker/process: local coordinator; hosted CI pending for PR feat: add advisory doc drift preview #143
• last action: opened PR feat: add advisory doc drift preview #143
• next automatic action: poll hosted CI, fix in-scope failures, then stop at public LifeOS merge approval gate if green
• Marcus needed: no
• stop reason: n/a

Boundary held: no cron/scheduler activation, no live GitHub issue creation/comment/close from product code, no provider/model/credential/runtime/gateway action, no doc auto-fix, no authority promotion/demotion.

[marcusglee11]

PR #143 CI green — merge gate reached

Active work:

• working: no
• current carrier: LifeOS Implement advisory documentation drift sweep issue creator #122 under parent Tracking: Doc-Drift Merge Gate (#117 + #122 + #125) #141 / ROI queue #1052
• worker/process: none
• last action: read back hosted CI for PR feat: add advisory doc drift preview #143
• next automatic action: if Marcus approves merge, merge exact head and run post-merge verification; otherwise keep PR open
• Marcus needed: yes
• stop reason: public/LifeOS merge approval gate

Hosted CI readback for PR #143:

PR=https://github.com/marcusglee11/LifeOS/pull/143
state=OPEN
head=aa6cf6f7415704367ef6999e0187bf7b9b514fbd
mergeStateStatus=CLEAN
Test Suite (Python 3.11): SUCCESS
Test Suite (Python 3.12): SUCCESS
Quality Gate: SUCCESS
Documentation Validation: SUCCESS
Validate Artefact Index: SUCCESS

Recommendation: approve merge of PR #143 exact head aa6cf6f7415704367ef6999e0187bf7b9b514fbd.

Boundary held: no merge performed yet; no cron/scheduler activation, no live GitHub issue creation/comment/close from product code, no release/runtime/provider/credential/destructive action.