{"record":{"id":"d5bd0636373a372d","repo":"nikivdev/code","slug":"session-is-not-eligible-for-promotion","errorCode":null,"errorMessage":"session is not eligible for promotion","messagePattern":"session is not eligible for promotion","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"src/codex_session_docs.rs","lineNumber":393,"sourceCode":"    let preview = SessionPromotionPreview {\n        session_id: packet.session_id.clone(),\n        session_key: session_key.clone(),\n        target_path: target_path.clone(),\n        eligible: entries[entry_index].promotion_eligible.unwrap_or(false),\n        review_state: entries[entry_index].doc_review_state.clone(),\n        promotion_reason: entries[entry_index]\n            .promotion_reason\n            .clone()\n            .unwrap_or_else(|| \"no promotion reason recorded\".to_string()),\n        blocked_reason: entries[entry_index].blocked_reason.clone(),\n        markdown,\n    };\n    if !apply {\n        write_review_queue_entries(&queue_path, &entries)?;\n        return Ok(preview);\n    }\n    if !preview.eligible {\n        bail!(\n            \"{}\",\n            preview\n                .blocked_reason\n                .clone()\n                .unwrap_or_else(|| \"session is not eligible for promotion\".to_string())\n        );\n    }\n\n    let promoted_path = resolve_project_relative_path(project_root, &target_path);\n    if let Some(parent) = promoted_path.parent() {\n        fs::create_dir_all(parent)\n            .with_context(|| format!(\"failed to create {}\", parent.display()))?;\n    }\n    fs::write(&promoted_path, &preview.markdown)\n        .with_context(|| format!(\"failed to write {}\", promoted_path.display()))?;\n\n    let promoted_path_string = promoted_path.display().to_string();\n    if !entries[entry_index]","sourceCodeStart":375,"sourceCodeEnd":411,"githubUrl":"https://github.com/nikivdev/code/blob/a747e741ae92c09071d0ae946ab48488adcff1ce/src/codex_session_docs.rs#L375-L411","documentation":"This library refuses to promote a codex session into documentation when the pre-computed preview reports the session as ineligible. The error surfaces `preview.blocked_reason` when one is set, otherwise a generic message. It is a deliberate guard so only sessions that passed all eligibility checks (e.g. clean state, required docs present) get promoted.","triggerScenarios":"Calling the doc promotion flow (after the `apply` flag is set and the preview was computed) while `preview.eligible == false`; the blocked reason stored in the preview is bubbled up verbatim.","commonSituations":"Running promotion on a session whose doc artifacts were never generated, on a session already promoted, or on a session that failed a prerequisite check earlier in the pipeline.","solutions":["Read the `blocked_reason` printed in the error (or rerun the preview step) to see the exact ineligibility cause","Fix the underlying cause (generate/repair the session docs, complete prerequisites) and rerun promotion","If the session was already promoted, skip it instead of re-running promotion"],"exampleFix":"// before\napply_promotion(preview);\n// after\nif preview.eligible {\n    apply_promotion(preview);\n} else {\n    eprintln!(\"skipped: {}\", preview.blocked_reason.as_deref().unwrap_or(\"ineligible\"));\n}","handlingStrategy":"validation","validationCode":"if !preview.eligible {\n    eprintln!(\"skipping promotion: {}\", preview.blocked_reason.as_deref().unwrap_or(\"ineligible\"));\n    return;\n}\napply_promotion(preview);","typeGuard":"fn is_promotable(preview: &Preview) -> bool {\n    preview.eligible && preview.blocked_reason.is_none()\n}","tryCatchPattern":"match promote(preview) {\n    Ok(result) => result,\n    Err(e) if e.to_string().contains(\"not eligible\") => skip_session(&e.to_string()),\n    Err(e) => return Err(e),\n}","preventionTips":["Always run and inspect the preview step before applying promotion","Check `preview.eligible` and `blocked_reason` before opting into apply mode","Only promote sessions whose doc artifacts completed successfully"],"tags":["session","docs","promotion","precondition"],"backgroundTag":"session-not-eligible","analyzedSha":"a747e741ae92c09071d0ae946ab48488adcff1ce","analyzedAt":"2026-09-01T22:43:55.719Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}