[codex] Harden ledger state handling

CHANGELOG.md

@@ -20,6 +20,9 @@ This project uses a lightweight changelog format:
 
 ### Fixed
 
+- Hardened goal and findings ledgers against malformed state, concurrent findings writes, and failed forced plan replacement.
+- Made coverage checking tolerate source markdown that starts below an H1 heading.
+- Aligned release, contributor, README, and provider-bridge examples with the current package layout and verification commands.
 - Removed the fabricated `claude_behavior > critical_child_safety_instructions` row from the coverage matrix. The heading does not exist in the pinned upstream `CLAUDE-FABLE-5.md` (commit `dc626fed`); it was added under a stale assumption. Coverage is now an honest 71/71.
 - The CI workflow now fetches the pinned upstream FABLE-5 source and passes it to `fable_coverage.py --source`. Previously the validator ran with no `--source`, which made the matrix self-consistent and could not detect fabricated rows.
 - Added `test_coverage_matrix_validates_against_pinned_source` and `test_ci_workflow_validates_against_pinned_source` so this regression cannot recur.

CONTRIBUTING.md

@@ -15,18 +15,22 @@ Thanks for helping improve FableCodex. This project is a Codex-native workflow p
 This repository intentionally uses the Python standard library for tests.
 
 ```bash
-python -m unittest discover -s tests -v
-python plugins/codex-fable5/skills/codex-fable5/scripts/fable_coverage.py
+python3 -m unittest discover -s tests -v
+python3 plugins/codex-fable5/skills/codex-fable5/scripts/fable_coverage.py
 ```
 
 Before opening a pull request, also run:
 
 ```bash
-python -m py_compile \
+python3 -m py_compile \
+  plugins/codex-fable5/skills/codex-fable5/scripts/codex_findings.py \
   plugins/codex-fable5/skills/codex-fable5/scripts/codex_goals.py \
   plugins/codex-fable5/skills/codex-fable5/scripts/fable_coverage.py \
   plugins/codex-fable5/skills/codex-fable5/scripts/make_litellm_config.py \
   tests/test_scripts.py
+sh -n plugins/codex-fable5/bin/codex-fable5
+sh -n plugins/codex-fable5/bin/codex-findings
+sh -n plugins/codex-fable5/bin/codex-goals
 ```
 
 ## Contribution Rules
@@ -45,4 +49,3 @@ python -m py_compile \
 - Any current product, model, API, or provider claim is verified against an official source.
 - Documentation is updated when user-facing behavior changes.
 - Licensing and attribution notes remain accurate.
-

README.ja.md

@@ -169,7 +169,7 @@ codex-fable5 findings add \
   --title "最終検証の不足" \
   --severity high \
   --source review \
-  --location "plugins/codex-fable5/skills/codex-fable5/scripts/codex_goals.py:180" \
+  --location "plugins/codex-fable5/skills/codex-fable5/scripts/codex_goals.py" \
   --evidence "テスト実行の証拠がなくても final checkpoint が完了できる。"
 ```
 

README.ko.md

@@ -169,7 +169,7 @@ codex-fable5 findings add \
   --title "최종 검증 누락" \
   --severity high \
   --source review \
-  --location "plugins/codex-fable5/skills/codex-fable5/scripts/codex_goals.py:180" \
+  --location "plugins/codex-fable5/skills/codex-fable5/scripts/codex_goals.py" \
   --evidence "테스트 실행 증거가 없어도 final checkpoint가 완료될 수 있다."
 ```
 

README.md

@@ -169,7 +169,7 @@ codex-fable5 findings add \
   --title "Missing final verification" \
   --severity high \
   --source review \
-  --location "plugins/codex-fable5/skills/codex-fable5/scripts/codex_goals.py:180" \
+  --location "plugins/codex-fable5/skills/codex-fable5/scripts/codex_goals.py" \
   --evidence "Final checkpoint can complete without proof that tests ran."
 ```
 

README.zh-CN.md

@@ -169,7 +169,7 @@ codex-fable5 findings add \
   --title "缺少最终验证" \
   --severity high \
   --source review \
-  --location "plugins/codex-fable5/skills/codex-fable5/scripts/codex_goals.py:180" \
+  --location "plugins/codex-fable5/skills/codex-fable5/scripts/codex_goals.py" \
   --evidence "即使没有测试运行证明，final checkpoint 也可以完成。"
 ```
 

README.zh-TW.md

@@ -169,7 +169,7 @@ codex-fable5 findings add \
   --title "缺少最終驗證" \
   --severity high \
   --source review \
-  --location "plugins/codex-fable5/skills/codex-fable5/scripts/codex_goals.py:180" \
+  --location "plugins/codex-fable5/skills/codex-fable5/scripts/codex_goals.py" \
   --evidence "即使沒有測試執行證明，final checkpoint 也可以完成。"
 ```
 

docs/RELEASING.md

@@ -29,8 +29,9 @@ python3 plugins/codex-fable5/skills/codex-fable5/scripts/fable_coverage.py
 8. Tag the release with the plugin version, for example:
 
 ```bash
-git tag v0.3.1
-git push origin main --tags
+VERSION=$(python3 -c 'import json; print(json.load(open("plugins/codex-fable5/.codex-plugin/plugin.json"))["version"])')
+git tag "v${VERSION}"
+git push origin main "v${VERSION}"
 ```
 
 9. Create a GitHub release that summarizes user-visible changes and links to the changelog.

examples/codex-config.litellm.toml

@@ -1,7 +1,9 @@
 # Example only. Put provider routing in user-level ~/.codex/config.toml.
+# Replace placeholders with a model that official Anthropic docs and your account
+# currently show as available, and with the matching LiteLLM alias.
 
 model_provider = "litellm-fable5"
-model = "claude-fable-5"
+model = "your-codex-model-alias"
 
 [model_providers.litellm-fable5]
 name = "LiteLLM Fable 5"

examples/litellm-fable5.yaml

@@ -1,7 +1,9 @@
+# Example only. Replace placeholders with a model that official Anthropic docs
+# and your account currently show as available.
 model_list:
-  - model_name: "claude-fable-5"
+  - model_name: "your-codex-model-alias"
     litellm_params:
-      model: "anthropic/claude-fable-5"
+      model: "anthropic/replace-with-current-anthropic-model"
       api_key: os.environ/ANTHROPIC_API_KEY
 
 litellm_settings:

plugins/codex-fable5/skills/codex-fable5/references/provider-bridge.md

@@ -25,8 +25,8 @@ Generate a starter LiteLLM config:
 
 ```bash
 python3 plugins/codex-fable5/skills/codex-fable5/scripts/make_litellm_config.py \
-  --model claude-fable-5 \
-  --alias claude-fable-5 \
+  --model replace-with-current-anthropic-model \
+  --alias your-codex-model-alias \
   --output litellm-fable5.yaml
 ```
 
@@ -36,7 +36,7 @@ Put provider config in your user-level `~/.codex/config.toml`, not in a project-
 
 ```toml
 model_provider = "litellm-fable5"
-model = "claude-fable-5"
+model = "your-codex-model-alias"
 
 [model_providers.litellm-fable5]
 name = "LiteLLM Fable 5"