Pre-flight Checklist
📝 Bug Description
docs/architecture/rdd-shadow-evaluation.md still documents the GENTLE_AI_RDD_SHADOW=1 opt-in switch as current, operator-facing guidance, but the switch and its shadow observer were removed from the codebase in RDD root simplification Wave 7 S2a (commit 17e40eb0, "retire the Wave 1 shadow observer surface").
On current upstream main (69ac5a45), GENTLE_AI_RDD_SHADOW appears in the code only in comments stating it was retired, for example internal/reviewtransaction/candidate_relation.go:8: "the Wave 1 shadow observer that also called it (shadow_observer.go, GENTLE_AI_RDD_SHADOW) retired in Wave 7 S2a". There is no environment-variable reader left, and shadow_observer.go no longer exists. The doc remains as an actionable "Quick path" that tells readers to set the switch and watch stderr for a gentle-ai.rdd-shadow/v1 line that can never be emitted.
🔄 Steps to Reproduce
- Check out current upstream
main (69ac5a45).
- Read
docs/architecture/rdd-shadow-evaluation.md, "Quick path" section (lines 7-8): "To opt in for local investigation, set GENTLE_AI_RDD_SHADOW=1 before running a gate".
- Grep the codebase for
GENTLE_AI_RDD_SHADOW: only comments remain, all saying the switch was retired in Wave 7 S2a.
- Run any gate with
GENTLE_AI_RDD_SHADOW=1 set: no gentle-ai.rdd-shadow/v1 line is ever written, because shadow_observer.go and shadowObservationEnvVar were deleted in Wave 7 S2a (commit 17e40eb0).
✅ Expected Behavior
docs/architecture/rdd-shadow-evaluation.md is updated or removed so it no longer instructs users to set a switch that does not exist. If shadow evaluation is retired, the doc should say so (or be deleted), matching the Wave 7 outcome.
❌ Actual Behavior
The doc presents a removed switch as current guidance. A reader following it sets an environment variable that has no effect and waits for stderr output that cannot appear.
🖥️ Environment
- Gentle AI Version: main @
69ac5a45 (documentation-only defect; no installed release involved)
- Operating System: Linux (Arch/Manjaro)
- AI Agent / Client: Other
- Affected Area: Documentation
💡 Logs / Error Output
N/A - documentation-only report; no runtime logs.
Additional Context
- Evidence of removal: commit
17e40eb0 ("feat(reviewtransaction): retire the Wave 1 shadow observer surface", Wave 7 WU4+WU5+WU6) removes ObserveShadowRelation (shadow_observer.go), shadowObservationEnvVar, and all 5 consumers. It is an ancestor of upstream main.
- The Wave 7 change (
openspec/changes/rdd-root-simplification-wave7) records the observer as fully retired and does not plan any update to docs/architecture/rdd-shadow-evaluation.md, so this doc is stale rather than intentionally historical.
- This is a post-removal documentation accuracy defect (the removal has landed on
main); it is not reporting an in-flight or planned redesign mismatch.
Pre-flight Checklist
status:approved📝 Bug Description
docs/architecture/rdd-shadow-evaluation.mdstill documents theGENTLE_AI_RDD_SHADOW=1opt-in switch as current, operator-facing guidance, but the switch and its shadow observer were removed from the codebase in RDD root simplification Wave 7 S2a (commit17e40eb0, "retire the Wave 1 shadow observer surface").On current upstream
main(69ac5a45),GENTLE_AI_RDD_SHADOWappears in the code only in comments stating it was retired, for exampleinternal/reviewtransaction/candidate_relation.go:8: "the Wave 1 shadow observer that also called it (shadow_observer.go, GENTLE_AI_RDD_SHADOW) retired in Wave 7 S2a". There is no environment-variable reader left, andshadow_observer.gono longer exists. The doc remains as an actionable "Quick path" that tells readers to set the switch and watch stderr for agentle-ai.rdd-shadow/v1line that can never be emitted.🔄 Steps to Reproduce
main(69ac5a45).docs/architecture/rdd-shadow-evaluation.md, "Quick path" section (lines 7-8): "To opt in for local investigation, setGENTLE_AI_RDD_SHADOW=1before running a gate".GENTLE_AI_RDD_SHADOW: only comments remain, all saying the switch was retired in Wave 7 S2a.GENTLE_AI_RDD_SHADOW=1set: nogentle-ai.rdd-shadow/v1line is ever written, becauseshadow_observer.goandshadowObservationEnvVarwere deleted in Wave 7 S2a (commit17e40eb0).✅ Expected Behavior
docs/architecture/rdd-shadow-evaluation.mdis updated or removed so it no longer instructs users to set a switch that does not exist. If shadow evaluation is retired, the doc should say so (or be deleted), matching the Wave 7 outcome.❌ Actual Behavior
The doc presents a removed switch as current guidance. A reader following it sets an environment variable that has no effect and waits for stderr output that cannot appear.
🖥️ Environment
69ac5a45(documentation-only defect; no installed release involved)💡 Logs / Error Output
N/A - documentation-only report; no runtime logs.
Additional Context
17e40eb0("feat(reviewtransaction): retire the Wave 1 shadow observer surface", Wave 7 WU4+WU5+WU6) removesObserveShadowRelation(shadow_observer.go),shadowObservationEnvVar, and all 5 consumers. It is an ancestor of upstreammain.openspec/changes/rdd-root-simplification-wave7) records the observer as fully retired and does not plan any update todocs/architecture/rdd-shadow-evaluation.md, so this doc is stale rather than intentionally historical.main); it is not reporting an in-flight or planned redesign mismatch.