baskduf · baskduf · Jun 15, 2026 · Jun 15, 2026 · Jun 15, 2026
@@ -32,10 +32,14 @@ jobs:
       - name: Compile scripts
         run: |
           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
 
       - name: Validate coverage matrix
         run: python3 plugins/codex-fable5/skills/codex-fable5/scripts/fable_coverage.py
@@ -11,6 +11,15 @@ This project uses a lightweight changelog format:
 
 ## Unreleased
 
+### Added
+
+- Added `codex_findings.py` to track evidence-backed review findings and gate final completion.
+- Added the `codex-fable5` wrapper command for checkout-based terminal use, with `codex-findings` and `codex-goals` as advanced aliases.
+
+### Changed
+
+- Integrated open or blocked findings into the final `codex_goals.py` checkpoint gate.
+
 ## 0.3.1 - 2026-06-15
 
 ### Added

@@ -32,6 +32,7 @@ It helps Codex work in a more structured way: inspect first, track goals, gather
 
 - Adds a Fable-style, tool-first agent loop for coding and research tasks.
 - Provides a simple goal ledger with evidence checkpoints.
+- Provides a findings ledger for review issues that must be resolved before final completion.
 - Encourages conclusion-first answers, clue-first debugging, and cheapest useful checks first.
 - Adds an optional final verification gate before claiming success.
 - Tracks `CLAUDE-FABLE-5.md` source-heading coverage with explicit Codex decisions.
@@ -75,24 +76,96 @@ In Codex:
 ```text
 Use $codex-fable5 to analyze this project.
 
+Use $codex-fable5 to do this with findings tracking.
+
 $codex-fable5로 이 프로젝트를 분석해줘.
 
+$codex-fable5로 이 작업 진행하고, 리뷰 findings도 추적해줘.
+
 $codex-fable5 を使って、このプロジェクトを分析してください。
 
+$codex-fable5 を使ってこの作業を進め、レビュー findings も追跡してください。
+
 请使用 $codex-fable5 分析这个项目。
 
+请使用 $codex-fable5 完成这项工作，并跟踪审查 findings。
+
 請使用 $codex-fable5 分析這個專案。
+
+請使用 $codex-fable5 完成這項工作，並追蹤審查 findings。
+```
+
+Use the local helper from a checkout:
+
+```bash
+export PATH="$PWD/plugins/codex-fable5/bin:$PATH"
+codex-fable5 status
 ```
 
-Create a simple multi-goal ledger:
+Without changing `PATH`, run them by path:
 
 ```bash
-python3 plugins/codex-fable5/skills/codex-fable5/scripts/codex_goals.py create --brief "Migration" \
+plugins/codex-fable5/bin/codex-fable5 status
+```
+
+For longer work, create a goal ledger:
+
+```bash
+codex-fable5 goals create --brief "Migration" \
   --goal "inspect::Find current behavior and tests" \
   --goal "change::Implement the migration" \
   --goal "verify::Run tests and inspect output"
 ```
 
+Track review findings before final completion:
+
+```bash
+codex-fable5 findings add \
+  --title "Unresolved review issue" \
+  --severity high \
+  --source subagent \
+  --evidence "Review found a missing final gate."
+codex-fable5 findings gate
+```
+
+Final goal completion also fails while open or blocked findings remain. `codex-goals` and `codex-findings` are still available as advanced aliases.
+
+---
+
+## Findings Gate
+
+The findings gate is an optional review closeout flow for work where missed issues are costly.
+
+Use it when:
+
+- A review or sub-agent finds actionable issues.
+- Verification is uncertain or failed once.
+- The task touches several files, migrations, security-sensitive code, or release behavior.
+
+Do not use it for simple edits or routine answers.
+
+In normal Codex use, ask for it in the prompt:
+
+```text
+Use $codex-fable5 to implement this and track findings before final completion.
+```
+
+For terminal use, add findings as accepted repair work:
+
+```bash
+codex-fable5 findings add \
+  --title "Missing final verification" \
+  --evidence "Review found no command output proving the final state."
+codex-fable5 findings next
+codex-fable5 findings resolve \
+  --id F001 \
+  --evidence "Added final verification." \
+  --verify-evidence "Tests passed and final status was checked."
+codex-fable5 findings gate
+```
+
+`codex-fable5 goals checkpoint --status complete` will fail while open or blocked findings remain.
+
 ---
 
 ## Measure Fable 5 Coverage

@@ -13,10 +13,14 @@ This project uses a lightweight release process because it is a small Codex plug
 ```bash
 python3 -m unittest discover -s tests -v
 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
 python3 plugins/codex-fable5/skills/codex-fable5/scripts/fable_coverage.py
 ```
 

@@ -12,6 +12,7 @@ Use this guidance when you want a repo to default to a Fable-style Codex workflo
 - Implement requested changes when feasible; do not stop at a proposal unless asked.
 - Verify every meaningful change with tests, lint, typecheck, command output, screenshots, or source inspection.
 - If verification fails, iterate before returning the task.
+- For review-sensitive work, track evidence-backed findings explicitly and close them with verification evidence before final completion.
 
 ## Investigation And Diagnosis
 
@@ -46,6 +47,7 @@ Use this guidance when you want a repo to default to a Fable-style Codex workflo
 - Lead with the outcome or recommendation.
 - Prefer readable prose over compressed fragments.
 - Use 2-pass review only for high-cost misses: missing requirements, factual/numeric errors, unexplained clues, or length/scope violations.
+- Treat accepted review findings as repair work, not suggestions to remember informally.
 
 ## Boundaries
 

@@ -1,7 +1,7 @@
 {
   "name": "codex-fable5",
   "version": "0.3.1",
-  "description": "Fable-style Codex workflow with source-section coverage, goal gates, verification grounding, VFF routing, and optional provider bridge guidance.",
+  "description": "Fable-style Codex workflow with source-section coverage, goal and findings gates, verification grounding, VFF routing, and optional provider bridge guidance.",
   "author": {
     "name": "Codex Fable5 Maintainers"
   },
@@ -11,7 +11,7 @@
   "interface": {
     "displayName": "Codex Fable5",
     "shortDescription": "Fable-style gates and routing.",
-    "longDescription": "Codex Fable5 packages a Codex-native skill that adapts Claude Fable 5, fablize, and Value-for-Fable ideas into a tool-first workflow with source-section coverage accounting, evidence checkpoints, verification grounding, clue-first diagnosis, cost-aware routing, optional 2-pass review, and LiteLLM provider bridge guidance for users who already have authorized Anthropic model access.",
+    "longDescription": "Codex Fable5 packages a Codex-native skill that adapts Claude Fable 5, fablize, and Value-for-Fable ideas into a tool-first workflow with source-section coverage accounting, evidence checkpoints, review findings gates, verification grounding, clue-first diagnosis, cost-aware routing, optional 2-pass review, and LiteLLM provider bridge guidance for users who already have authorized Anthropic model access.",
     "developerName": "Codex Fable5 Maintainers",
     "category": "Productivity",
     "capabilities": ["Skills"],

@@ -0,0 +1,53 @@
+#!/usr/bin/env sh
+set -eu
+
+SCRIPT_DIR=$(CDPATH= cd "$(dirname "$0")" && pwd)
+GOALS="$SCRIPT_DIR/../skills/codex-fable5/scripts/codex_goals.py"
+FINDINGS="$SCRIPT_DIR/../skills/codex-fable5/scripts/codex_findings.py"
+
+usage() {
+  cat <<'EOF'
+Usage:
+  codex-fable5 status
+  codex-fable5 goals <command> [args...]
+  codex-fable5 findings <command> [args...]
+
+Examples:
+  codex-fable5 status
+  codex-fable5 findings add --title "Missing verification" --evidence "No test evidence"
+  codex-fable5 findings gate
+  codex-fable5 goals next
+EOF
+}
+
+if [ "$#" -eq 0 ]; then
+  usage
+  exit 0
+fi
+
+case "$1" in
+  -h|--help|help)
+    usage
+    ;;
+  status)
+    python3 "$FINDINGS" status
+    if [ -f ".codex-fable5/goals.json" ]; then
+      python3 "$GOALS" status
+    else
+      printf '%s\n' "codex-fable5: no goal plan"
+    fi
+    ;;
+  findings|finding|f)
+    shift
+    exec python3 "$FINDINGS" "$@"
+    ;;
+  goals|goal|g)
+    shift
+    exec python3 "$GOALS" "$@"
+    ;;
+  *)
+    printf '%s\n' "codex-fable5: unknown command '$1'" >&2
+    usage >&2
+    exit 2
+    ;;
+esac
@@ -0,0 +1,5 @@
+#!/usr/bin/env sh
+set -eu
+
+SCRIPT_DIR=$(CDPATH= cd "$(dirname "$0")" && pwd)
+exec python3 "$SCRIPT_DIR/../skills/codex-fable5/scripts/codex_findings.py" "$@"
@@ -0,0 +1,5 @@
+#!/usr/bin/env sh
+set -eu
+
+SCRIPT_DIR=$(CDPATH= cd "$(dirname "$0")" && pwd)
+exec python3 "$SCRIPT_DIR/../skills/codex-fable5/scripts/codex_goals.py" "$@"
@@ -52,6 +52,7 @@ Use this skill to translate Fable-style behavior into Codex behavior. It does no
    - Prefer real tools, tests, rendered artifacts, and current sources over memory.
    - Implement the requested change, not only a proposal, unless the user clearly asks for analysis only.
    - Verify with the narrowest strong evidence that covers the requirement: tests, lint, typecheck, screenshots, command output, source inspection, or connector readback.
+   - For review-sensitive work, use `scripts/codex_findings.py` to track evidence-backed findings and require the findings gate to pass before final completion.
    - If verification fails, iterate once or more before handing the issue back.
    - Summarize what changed, what was verified, and any residual risk.
 
@@ -102,5 +103,7 @@ Use the smallest durable surface that fits:
 ## Scripts
 
 - Run `scripts/codex_goals.py` for a local, stdlib-only multi-story ledger with evidence checkpoints and a final verification gate.
+- Run `scripts/codex_findings.py` for a local, stdlib-only review findings ledger. Final `codex_goals.py` checkpoints fail while open or blocked findings remain.
+- For user-facing terminal use from a checkout, add `plugins/codex-fable5/bin` to `PATH` and run `codex-fable5 status`, `codex-fable5 goals ...`, or `codex-fable5 findings ...`.
 - Run `scripts/fable_coverage.py --source /path/to/CLAUDE-FABLE-5.md` to verify that every source heading is accounted for in `references/coverage-matrix.md`.
 - Run `scripts/make_litellm_config.py` to generate a LiteLLM config for an Anthropic model alias. Use this only after confirming the user has a valid Anthropic key and model access.
@@ -53,6 +53,13 @@ Review criteria:
 - Clues the explanation does not cover.
 - Length, scope, or format violations.
 
+When a review finds actionable issues, track them as findings instead of relying on memory. Use the findings ledger for review-sensitive work:
+
+- Add only evidence-backed findings.
+- Resolve accepted findings through the normal inspect, change, verify loop.
+- Re-review only unresolved or materially changed areas.
+- Run the findings gate before final completion when open findings may remain; final goal checkpoints also fail while blocking findings remain.
+
 Keep the review narrow. Do not invent new standards during review, and do not rewrite a passing draft for taste.
 
 ## Writing And Research

@@ -24,6 +24,7 @@ From `value-for-fable`:
 - Outcome-first readable communication.
 - Clue-first diagnosis and cheapest discriminating measurement.
 - Optional 2-pass review for high-cost misses.
+- Evidence-backed findings closeout for review issues.
 - Long-session drift awareness.
 - Avoiding over-compression when readability and completeness matter.
 

@@ -11,22 +11,25 @@ This reference adapts the useful procedural ideas from `fablize` and `value-for-
 | HTML, CSS, SVG, game, canvas, chart, UI, animation, local app | Use verification grounding: run, observe, fix, re-run after changes. |
 | Diagnosis, architecture decision, product/technical tradeoff | Use VFF operating structure: conclusion first, clue-first hypothesis, cheapest discriminating measurement. |
 | High-stakes or deep unfamiliar domain | Suggest higher reasoning or stronger model; optionally use 2-pass review. |
+| Review requested, failed/uncertain verification, security-sensitive change, or multi-file work with costly misses | Use the findings ledger and gate. |
 | Simple one-step edit or factual answer | Keep the normal Codex loop; do not add goal files or extra process. |
 
 ## Goal Ledger
 
 Use `scripts/codex_goals.py` when there are multiple dependent stories and the task benefits from resume-safe state.
 
+For user-facing terminal use from a checkout, add `plugins/codex-fable5/bin` to `PATH` and use `codex-fable5 goals`.
+
 Example:
 
 ```bash
-python3 plugins/codex-fable5/skills/codex-fable5/scripts/codex_goals.py create --brief "Add CSV import" \
+codex-fable5 goals create --brief "Add CSV import" \
   --goal "inspect::Find current import flow and tests" \
   --goal "implement::Add CSV parser and UI path" \
   --goal "verify::Run tests and a sample import"
-python3 plugins/codex-fable5/skills/codex-fable5/scripts/codex_goals.py next
-python3 plugins/codex-fable5/skills/codex-fable5/scripts/codex_goals.py checkpoint --id G001 --status complete --evidence "Read importer.ts and import.test.ts"
-python3 plugins/codex-fable5/skills/codex-fable5/scripts/codex_goals.py next
+codex-fable5 goals next
+codex-fable5 goals checkpoint --id G001 --status complete --evidence "Read importer.ts and import.test.ts"
+codex-fable5 goals next
 ```
 
 Rules:
@@ -37,6 +40,40 @@ Rules:
 - On resume, run `status` first.
 - Store local state under `.codex-fable5/`; do not commit it unless the user asks.
 
+## Findings Ledger
+
+Use `scripts/codex_findings.py` when review or verification produces evidence-backed issues that must not be lost before final completion.
+
+For user-facing terminal use from a checkout, add `plugins/codex-fable5/bin` to `PATH` and use `codex-fable5 findings`.
+
+Example:
+
+```bash
+codex-fable5 findings add \
+  --title "Final checkpoint can pass with unresolved review issues" \
+  --severity high \
+  --source subagent \
+  --evidence "Review found that the final gate only checks tests, not accepted findings."
+codex-fable5 findings next
+codex-fable5 findings resolve \
+  --id F001 \
+  --evidence "Added a findings gate before final checkpoint." \
+  --verify-cmd "python3 -m unittest discover -s tests -v" \
+  --verify-evidence "all tests passed"
+codex-fable5 findings gate
+```
+
+Rules:
+
+- Treat findings as accepted repair work, not brainstorming notes.
+- Add only evidence-backed missing requirements, regressions, factual/source errors, failed checks, or unexplained clues.
+- When a goal is active, new findings attach to that goal automatically unless `--goal` is provided.
+- Resolve findings only after the normal inspect/change/verify loop produces resolution evidence and verification evidence.
+- Run `gate` before completing a final goal checkpoint when accepted findings may remain.
+- Final `codex-fable5 goals checkpoint --status complete` also fails while open or blocked findings remain.
+- By default, `gate` fails on open or blocked findings. Use `--allow-blocked` only when the remaining blocked findings are explicitly accepted as residual risk.
+- Store local state under `.codex-fable5/`; do not commit it unless the user asks.
+
 ## Investigation Protocol
 
 For unknown-cause debugging: