Tracking: Doc-Drift Merge Gate (#117 + #122 + #125)

[marcusglee11]

Objective

Tracking umbrella for completing the doc-drift merge gate work. Consolidates three existing issues into one execution cursor so the COO can drive them to completion as a sequence.

Origin

AA (ChatGPT-5.5 via Oracle) ideation session, 2026-07-03. Ranked #5 in consolidated top-10.

Child issues (execution sequence)

1. #117 — Spec: make documentation drift control merge-enforced

• Status: OPEN, spec reviewed and approved (v3 operative spec, OpenClaw review, AA review completed)
• What remains: Convert approved spec to implementation. Build authority registry (YAML metadata), CI merge gate (fail-closed on drift), post-merge verification from clean origin/main.
• This is the gate. Implement advisory documentation drift sweep issue creator #122 and Add doc-entrypoint freshness check to maintenance sweeps #125 depend on it.

2. #122 — Implement advisory documentation drift sweep issue creator

• Status: OPEN, depends on Spec: make documentation drift control merge-enforced #117
• What remains: Build cron-driven sweep that detects drift bypassing the gate and opens evidence-backed reconciliation issues. Deduplicate. Never auto-fix docs.

3. #125 — Add doc-entrypoint freshness check to maintenance sweeps

• Status: OPEN, depends on Spec: make documentation drift control merge-enforced #117
• What remains: Add narrowest check — README / docs/INDEX.md / LIFEOS_STATE.md freshness. One named check in existing sweep suite.

Oracle guidance

Do a tight version. Avoid documentation governance theatre. Do not overbuild the advisory sweep until the hard gate works.

Execution plan

1. Spec: make documentation drift control merge-enforced #117: Implement authority registry + CI merge gate from approved v3 spec. Substantive code — dispatch via EA (ea-dispatch 3-phase plan/implement/review).
2. Implement advisory documentation drift sweep issue creator #122: After Spec: make documentation drift control merge-enforced #117 gate works, build advisory sweep. Detect drift, open issues, deduplicate. Wire into maintenance sweep after dry-run shows acceptable noise.
3. Add doc-entrypoint freshness check to maintenance sweeps #125: After Implement advisory documentation drift sweep issue creator #122, add doc-entrypoint freshness check as named check.

Acceptance criteria (all three)

• Spec: make documentation drift control merge-enforced #117: Authority registry with machine-checkable metadata for all tracked docs
• Spec: make documentation drift control merge-enforced #117: CI merge gate fails closed on drift
• Spec: make documentation drift control merge-enforced #117: Post-merge verification runs from clean origin/main
• Implement advisory documentation drift sweep issue creator #122: Sweep detects all 6 drift classes from Implement advisory documentation drift sweep issue creator #122 body
• Implement advisory documentation drift sweep issue creator #122: Each created issue has exact paths, evidence, authority class, recommended recovery, parent link
• Implement advisory documentation drift sweep issue creator #122: Duplicate detection prevents issue spam
• Add doc-entrypoint freshness check to maintenance sweeps #125: Entrypoint freshness check covers README, docs/INDEX.md, LIFEOS_STATE.md
• Add doc-entrypoint freshness check to maintenance sweeps #125: Clean state produces no issue spam

Authority boundary

• All three issues are private/internal/reversible
• EA dispatch for substantive code (Spec: make documentation drift control merge-enforced #117 implementation)
• Independent review required (cross-model or AA)
• No public/external writes, no merges without Marcus approval

[marcusglee11]

Checkpoint: #117 doc-drift merge gate — substrate landed

What changed

PR #142 opened: #142

Three new files implementing the approved v3 spec:

• tools/validate_doc_drift_gate.py — 4-check validator (reconciliation, authority transitions, derived freshness, emergency repair)
• .github/workflows/doc_drift_gate.yml — CI workflow on PRs touching docs/
• tests/test_doc_drift_gate.py — 12/12 tests passing

EA dispatch evidence

• Plan: DeepSeek Pro v4, $0.0562, 198s
• Implement: DeepSeek Flash v4
• Review: DeepSeek Pro v4, $0.0349, 80s, verdict AMEND → 6 findings addressed
• Parent verification: GLM-5.2, 12/12 tests, diff inspected, 3 parent-side bug fixes applied

Remaining for #117

• PR feat: CI-enforced doc drift merge gate (#117/#141) #142 CI checks pass (if CI is running)
• Marcus approves merge

Next in sequence

• Implement advisory documentation drift sweep issue creator #122 (advisory drift sweep) — after feat: CI-enforced doc drift merge gate (#117/#141) #142 merges
• Add doc-entrypoint freshness check to maintenance sweeps #125 (entrypoint freshness check) — after Implement advisory documentation drift sweep issue creator #122

Baton

PR #142 is open and ready for review. Merge requires Marcus approval.

[marcusglee11]

#141 / PR #142 Quality Gate fix pushed

Active work:

• working: yes
• current carrier: LifeOS Tracking: Doc-Drift Merge Gate (#117 + #122 + #125) #141 / PR feat: CI-enforced doc drift merge gate (#117/#141) #142 under parent #1052
• worker/process: local coordinator; hosted CI pending
• last action: diagnosed failing Quality Gate, applied formatting/ruff fixes, pushed commit 0b1a1be
• next automatic action: poll hosted CI, fix any in-scope failures, then checkpoint merge/gate state
• Marcus needed: no
• stop reason: n/a

Diagnosis:

• Hosted Quality Gate failed on blocking ruff/format issues in tools/validate_doc_drift_gate.py and tests/test_doc_drift_gate.py.
• Local target tests already passed; failure was quality-gate hygiene, not validator behavior.

Local verification after fix:

ruff check tests/__init__.py tests/test_doc_drift_gate.py tools/validate_doc_drift_gate.py
All checks passed!

ruff format --check tests/__init__.py tests/test_doc_drift_gate.py tools/validate_doc_drift_gate.py
3 files already formatted

python3 -m pytest tests/test_doc_drift_gate.py -q
12 passed

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

Caveat: local mypy and yamllint executables are not installed, but they are advisory in this quality gate and previously passed on hosted CI. Hosted CI is the final readback.

Boundary held: no merge, no release, no runtime/cron/provider/credential/destructive/public-external action.

[marcusglee11]

PR #142 CI green — merge gate reached

Active work:

• working: no
• current carrier: LifeOS Tracking: Doc-Drift Merge Gate (#117 + #122 + #125) #141 / PR feat: CI-enforced doc drift merge gate (#117/#141) #142 under parent #1052
• worker/process: none
• last action: pushed Quality Gate fix 0b1a1be0358ba70caabc209bcf793625e634015b and read back hosted CI
• next automatic action: if Marcus approves merge, merge exact head and run post-merge verification; otherwise keep PR open and continue later dependency-safe prep if available
• Marcus needed: yes
• stop reason: public/LifeOS merge approval gate

Hosted CI readback for PR #142:

mergeStateStatus=CLEAN
head=0b1a1be0358ba70caabc209bcf793625e634015b
Build Entry Gate (warn): SUCCESS
Documentation Drift Gate: SUCCESS
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 #142 exact head 0b1a1be0358ba70caabc209bcf793625e634015b.

Boundary held: no merge performed yet; no release, runtime/cron/provider/credential/destructive action.

[marcusglee11]

PR #142 merged and post-merge verified

Outcome: #117 doc-drift merge gate substrate is now merged to main.

PR: #142
Merge commit: 4fa4fd724188dc961a56644a4f28b9ab40df8aac

Pre-merge readback:

head=0b1a1be0358ba70caabc209bcf793625e634015b
mergeStateStatus=CLEAN
all hosted checks=SUCCESS

Post-merge verification from fresh origin/main:

HEAD=4fa4fd7 feat: CI-enforced doc drift merge gate (#117/#141) (#142)
python3 -m pytest tests/test_doc_drift_gate.py -q
12 passed
python3 tools/validate_doc_drift_gate.py --help
OK

Active work:

• working: yes
• current carrier: LifeOS Tracking: Doc-Drift Merge Gate (#117 + #122 + #125) #141 under parent #1052
• worker/process: local coordinator
• last action: merged feat: CI-enforced doc drift merge gate (#117/#141) #142 exact approved head and verified from origin/main
• next automatic action: read back Spec: make documentation drift control merge-enforced #117/Implement advisory documentation drift sweep issue creator #122/Add doc-entrypoint freshness check to maintenance sweeps #125 state and advance to Implement advisory documentation drift sweep issue creator #122 advisory documentation drift sweep if dependencies are satisfied
• Marcus needed: no
• stop reason: n/a

Boundary held: merge was exact-head approved; no release, runtime/cron/provider/credential/destructive action.

[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.