docs(codex): wire the compaction hook into README and codex-tools, add drift-cure footer

README gains the hook install step for Codex users (hooks.json merge,
one-time trust prompt, --dangerously-bypass-hook-trust for headless
automation). codex-tools.md aligns its claims with the mechanism — the
dispatch rules bind every spawn, the printed hints appear at scripted
boundaries, and the hook covers post-compaction re-grounding — and adds
a section telling controllers compaction sheds these instructions and
to treat every printed hint as authoritative.

The hints file gains a drift-cure footer both scripts print after the
role line: in the instrumented run that broke post-compaction,
reprinted hints alone did not heal the already-broken dispatch pattern
across three subsequent boundaries — recovery text must name the drift
and prescribe the re-read.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

README.md

@@ -98,6 +98,41 @@ Superpowers is available via the [official Codex plugin marketplace](https://git
 
 - Select `Install Plugin`.
 
+#### Codex: compaction re-injection hook (recommended)
+
+Codex compacts long sessions, replacing the transcript with a summary that
+drops Superpowers' skill instructions mid-run — long autonomous workflows
+(like subagent-driven-development) then drift back to harness defaults.
+Claude Code re-injects the bootstrap after every compaction; this hook
+restores the same behavior on Codex (0.145+).
+
+Merge `hooks/hooks-codex.json.example` from your Superpowers install into
+`~/.codex/hooks.json`, replacing the placeholder with the absolute path to
+your install:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"/path/to/superpowers/hooks/session-start-codex\"",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Codex asks you to trust the hook once, the first time it runs in the app.
+Headless automation (CI, eval harnesses) must pass
+`--dangerously-bypass-hook-trust` instead, because untrusted hooks are
+skipped silently.
+
 ### Cursor
 
 - In Cursor Agent chat, install from marketplace:

skills/subagent-driven-development/scripts/review-package

@@ -73,5 +73,9 @@ if [ -z "${CLAUDECODE:-}" ] && [ -f "$hints_file" ]; then
   hint_line=$(grep "^${hint_key}:" "$hints_file" | head -1 | cut -d: -f2- | sed 's/^ *//') || true
   if [ -n "$hint_line" ]; then
     echo "$hint_line"
+    footer_line=$(grep "^footer:" "$hints_file" | head -1 | cut -d: -f2- | sed 's/^ *//') || true
+    if [ -n "$footer_line" ]; then
+      echo "$footer_line"
+    fi
   fi
 fi

skills/subagent-driven-development/scripts/task-brief

@@ -52,5 +52,9 @@ if [ -z "${CLAUDECODE:-}" ] && [ -f "$hints_file" ]; then
   hint_line=$(grep "^implementer:" "$hints_file" | head -1 | cut -d: -f2- | sed 's/^ *//') || true
   if [ -n "$hint_line" ]; then
     echo "$hint_line"
+    footer_line=$(grep "^footer:" "$hints_file" | head -1 | cut -d: -f2- | sed 's/^ *//') || true
+    if [ -n "$footer_line" ]; then
+      echo "$footer_line"
+    fi
   fi
 fi

skills/using-superpowers/references/codex-dispatch.hints

@@ -5,6 +5,10 @@
 # Model names track Codex's spawn_agent allowlist (currently gpt-5.6-sol
 # and gpt-5.6-terra) — update this file when the allowlist changes.
 # Format: <role>: <line printed verbatim>
+# The footer line prints after every role line: prevention alone does not
+# cure drift — in instrumented runs, reprinted hints did not heal an
+# already-broken dispatch pattern until the text named the drift directly.
+footer: If any spawn this session omitted these params or used fork_turns "all", you have drifted — re-read references/codex-tools.md before dispatching again.
 implementer: dispatch (spawn_agent): fork_turns=none model=gpt-5.6-terra reasoning_effort=high
 task-review: dispatch (spawn_agent): fork_turns=none model=gpt-5.6-terra reasoning_effort=high
 fix-review: dispatch (spawn_agent): fork_turns=none model=gpt-5.6-terra reasoning_effort=medium

skills/using-superpowers/references/codex-tools.md

@@ -19,7 +19,9 @@ If your `spawn_agent` schema has `model` and `reasoning_effort`
 parameters (Codex 0.145+), set both on every dispatch: task-brief and
 review-package print a `dispatch:` hint line with the exact values —
 copy it onto the call verbatim, every time, even late in a long
-session. Those hints are the Model Selection mapping on Codex:
+session. The hints print at those scripts' boundaries; every other
+spawn — ad-hoc fan-outs included — follows the same table without a
+printed reminder. Those hints are the Model Selection mapping on Codex:
 reviewer tier never exceeds implementer tier, no fix round gets an
 effort bump, and rounds 4-5's "more capable model" means a fresh
 implementer at the same tier — needing more is a BLOCKED escalation
@@ -34,6 +36,19 @@ your model and effort with no override — role files in
 partner before starting a plan of more than a few tasks, and offer a
 lower-effort session instead.
 
+## Compaction sheds these instructions
+
+Context compaction replaces your transcript with a summary that keeps
+your progress but not your working instructions — the first
+post-compaction dispatch is where routing drift starts, and once one
+bare spawn lands, the broken pattern becomes its own precedent. The
+compaction re-injection hook (README, "Codex: compaction re-injection
+hook") restores the bootstrap after every compaction; recommend it to
+your human partner if it is not installed. Without it, the printed
+`dispatch:` hints are your only re-grounding — treat every one you see
+as authoritative, especially right after a summary appears in your
+context.
+
 ## Environment Detection
 
 Skills that create worktrees or finish branches should detect their

tests/claude-code/test-sdd-workspace.sh

@@ -175,9 +175,16 @@ PLAN
         echo "    got: $brief_hint"
     fi
 
+    if [[ "$brief_hint" == *"you have drifted"* ]]; then
+        pass "task-brief prints the drift-cure footer after the hint"
+    else
+        fail "task-brief prints the drift-cure footer after the hint"
+        echo "    got: $brief_hint"
+    fi
+
     local rp_hint
     rp_hint="$(cd "$repo" && env -u CLAUDECODE "$SDD_SCRIPTS/review-package" plan-a.md HEAD~1 HEAD)"
-    if [[ "$rp_hint" == *"dispatch (spawn_agent): fork_turns=none model=gpt-5.6-terra reasoning_effort=high"* ]]; then
+    if [[ "$rp_hint" == *"dispatch (spawn_agent): fork_turns=none model=gpt-5.6-terra reasoning_effort=high"* && "$rp_hint" == *"you have drifted"* ]]; then
         pass "review-package relays the default-role hint off Claude Code"
     else
         fail "review-package relays the default-role hint off Claude Code"