Optimize RLCR context reuse

Generate an immutable context-pack.md for each RLCR run and reference it from implementation and routine review prompts. The context pack carries a stable goal/AC digest, source identity, and source-of-truth rules, while the original plan remains authoritative and full-alignment reviews still read the full plan directly.

Keep routine review prompt prefixes stable by removing the round number from the title and moving round-specific payloads, summary content, commit history, prompt path, and review output path behind a Dynamic Round Payload section. Preserve existing review semantics such as Claude summary boundary markers, review intent wording, Original Implementation Plan headings, and the 1-2 target AC round contract rule.

Replace fragile sed-based plan goal/AC extraction with section-aware parsing so context-pack generation is reliable. Record the context pack path in loop state and pass it through stop-hook generated regular-review and next-round prompts, with fallback to the original plan for older loops without a context pack.

Final auxiliary validation showed regular review reusable-prefix ratio improving from 0.24% to 88.35%, average reusable prefix growing from 22 bytes to 5296 bytes, and a representative Round 0 prompt estimate dropping 72.2% by replacing embedded plan text with context references. Auxiliary validation tools are kept out of this commit and saved separately in stash.

Author: Tunglies

hooks/loop-codex-stop-hook.sh

@@ -1033,6 +1033,10 @@ fi
 
 # Calculate derived values for templates
 LOOP_TIMESTAMP=$(basename "$LOOP_DIR")
+CONTEXT_PACK_FILE=".humanize/rlcr/${LOOP_TIMESTAMP}/context-pack.md"
+if [[ ! -f "$PROJECT_ROOT/$CONTEXT_PACK_FILE" ]]; then
+    CONTEXT_PACK_FILE="$PLAN_FILE"
+fi
 COMPLETED_ITERATIONS=$((CURRENT_ROUND + 1))
 # Clamp previous round indices to 0 minimum to avoid negative file references
 # This can happen with --full-review-round 2 where first alignment check is at round 1
@@ -1084,13 +1088,21 @@ Review Claude's work against the plan and goal tracker. Check all goals are bein
 
 Write your review to {{REVIEW_RESULT_FILE}}. End with COMPLETE if done, or list issues."
 
-REGULAR_REVIEW_FALLBACK="# Code Review (Round {{CURRENT_ROUND}})
+REGULAR_REVIEW_FALLBACK="# Code Review
 
+Read @{{CONTEXT_PACK_FILE}} and @{{GOAL_TRACKER_FILE}} first. The original plan remains authoritative at @{{PLAN_FILE}}; read it if the stable context is insufficient or ambiguous.
 Review Claude's work for this round.
 
-## Claude's Summary
-{{SUMMARY_CONTENT}}
 
+## Dynamic Round Payload
+Round: {{CURRENT_ROUND}}
+
+---
+Below is Claude's summary of the work completed:
+<!-- CLAUDE's WORK SUMMARY START -->
+{{SUMMARY_CONTENT}}
+<!-- CLAUDE's WORK SUMMARY  END  -->
+---
 {{COMMIT_HISTORY_SECTION}}
 
 {{GOAL_TRACKER_UPDATE_SECTION}}
@@ -1118,6 +1130,7 @@ else
     load_and_render_safe "$TEMPLATE_DIR" "codex/regular-review.md" "$REGULAR_REVIEW_FALLBACK" \
         "CURRENT_ROUND=$CURRENT_ROUND" \
         "PLAN_FILE=$PLAN_FILE" \
+        "CONTEXT_PACK_FILE=$CONTEXT_PACK_FILE" \
         "PROMPT_FILE=$PROMPT_FILE" \
         "SUMMARY_CONTENT=$SUMMARY_CONTENT" \
         "GOAL_TRACKER_FILE=$GOAL_TRACKER_FILE" \
@@ -2069,6 +2082,7 @@ if [[ "$DRIFT_REPLAN_REQUIRED" == "true" ]]; then
         "PLAN_FILE=$PLAN_FILE" \
         "REVIEW_CONTENT=$REVIEW_CONTENT" \
         "GOAL_TRACKER_FILE=$GOAL_TRACKER_FILE" \
+        "CONTEXT_PACK_FILE=$CONTEXT_PACK_FILE" \
         "BITLESSON_FILE=$BITLESSON_FILE" \
         "ROUND_CONTRACT_FILE=$NEXT_CONTRACT_FILE" \
         "CURRENT_ROUND=$NEXT_ROUND" \
@@ -2079,6 +2093,7 @@ else
         "PLAN_FILE=$PLAN_FILE" \
         "REVIEW_CONTENT=$REVIEW_CONTENT" \
         "GOAL_TRACKER_FILE=$GOAL_TRACKER_FILE" \
+        "CONTEXT_PACK_FILE=$CONTEXT_PACK_FILE" \
         "BITLESSON_FILE=$BITLESSON_FILE" \
         "ROUND_CONTRACT_FILE=$NEXT_CONTRACT_FILE" \
         "CURRENT_ROUND=$NEXT_ROUND" \

prompt-template/claude/next-round-prompt.md

@@ -2,17 +2,23 @@ Your work is not finished. Read and execute the below with ultrathink.
 
 ## Original Implementation Plan
 
-**IMPORTANT**: Before proceeding, review the original plan you are implementing:
+**IMPORTANT**: Before proceeding, review the stable context pack first:
+@{{CONTEXT_PACK_FILE}}
+
+The original plan remains authoritative at:
 @{{PLAN_FILE}}
 
 This plan contains the full scope of work and requirements. Ensure your work aligns with this plan.
 
+Read the original plan whenever the context pack is insufficient, ambiguous, or conflicts with Codex feedback, code, summaries, or goal-tracker.md.
+
 ---
 
 ## Round Re-anchor (REQUIRED FIRST STEP)
 
 Before writing code:
-- Re-read @{{PLAN_FILE}}
+- Re-read @{{CONTEXT_PACK_FILE}}
+- Re-read @{{PLAN_FILE}} only if the context pack is insufficient, ambiguous, or in conflict with the review feedback
 - Re-read @{{GOAL_TRACKER_FILE}}
 - Re-read the most recent round summaries/reviews that led to this round
 - Write the current round contract to @{{ROUND_CONTRACT_FILE}}

prompt-template/codex/regular-review.md

@@ -1,23 +1,19 @@
-# Code Review - Round {{CURRENT_ROUND}}
+# Code Review
 
 ## Original Implementation Plan
 
 **IMPORTANT**: The original plan that Claude is implementing is located at:
 @{{PLAN_FILE}}
 
-You MUST read this plan file first to understand the full scope of work before conducting your review.
 This plan contains the complete requirements and implementation details that Claude should be following.
 
-Based on the original plan and @{{PROMPT_FILE}}, Claude claims to have completed the work. Please conduct a thorough critical review to verify this.
+For routine reviews, keep the reusable context prefix stable:
+- Read @{{CONTEXT_PACK_FILE}} and @{{GOAL_TRACKER_FILE}} first.
+- Do not re-read the original plan by default during routine review.
+- Read @{{PLAN_FILE}} if the context pack is insufficient, ambiguous, conflicts with the current summary, omits a requirement relevant to this round, or if an acceptance criterion, implementation boundary, plan change, deferral, or scope reinterpretation is unclear.
 
----
-Below is Claude's summary of the work completed:
-<!-- CLAUDE's WORK SUMMARY START -->
-{{SUMMARY_CONTENT}}
-<!-- CLAUDE's WORK SUMMARY  END  -->
----
+Based on the stable context and the current round prompt listed in the dynamic payload, Claude claims to have completed the work below. Please conduct a thorough critical review to verify this.
 
-{{COMMIT_HISTORY_SECTION}}
 
 ## Part 1: Implementation Review
 
@@ -37,7 +33,7 @@ Below is Claude's summary of the work completed:
 Read @{{GOAL_TRACKER_FILE}} and verify:
 
 1. **Acceptance Criteria Progress**: For each AC, is progress being made? Are any ACs being ignored?
-2. **Forgotten Items**: Are there tasks from the original plan that are not tracked in Active/Completed/Deferred?
+2. **Forgotten Items**: Are there tasks from the original plan that are not tracked in Active/Completed/Deferred? If the context pack is insufficient to answer this, read @{{PLAN_FILE}}.
 3. **Deferred Items**: Are deferrals justified? Do they block any ACs?
 4. **Plan Evolution**: If Claude modified the plan, is the justification valid?
 
@@ -68,9 +64,26 @@ If Claude mostly worked on queued side issues and failed to advance the mainline
 
 - In short, your review comments can include: problems/findings/blockers; claims that don't match reality; implementation plans for deferred work (to be implemented now); implementation plans for unfinished work; goal alignment issues.
 - Your output should be structured so Claude can tell which items are mainline gaps, blocking side issues, and queued side issues.
-- If after your investigation the actual situation does not match what Claude claims to have completed, or there is pending work to be done, output your review comments to @{{REVIEW_RESULT_FILE}}.
+- If after your investigation the actual situation does not match what Claude claims to have completed, or there is pending work to be done, output your review comments to the review result file listed in the dynamic payload.
 - **CRITICAL**: Only output "COMPLETE" as the last line if ALL tasks from the original plan are FULLY completed with no deferrals
   - DEFERRED items are considered INCOMPLETE - do NOT output COMPLETE if any task is deferred
   - UNFINISHED items are considered INCOMPLETE - do NOT output COMPLETE if any task is pending
   - The ONLY condition for COMPLETE is: all original plan tasks are done, all ACs are met, no deferrals or pending work allowed
 - The word COMPLETE on the last line will stop Claude.
+
+## Dynamic Round Payload
+
+Round: {{CURRENT_ROUND}}
+Current round prompt: @{{PROMPT_FILE}}
+
+Review result file: @{{REVIEW_RESULT_FILE}}
+
+
+---
+Below is Claude's summary of the work completed:
+<!-- CLAUDE's WORK SUMMARY START -->
+{{SUMMARY_CONTENT}}
+<!-- CLAUDE's WORK SUMMARY  END  -->
+---
+
+{{COMMIT_HISTORY_SECTION}}

scripts/setup-rlcr-loop.sh

@@ -56,9 +56,30 @@ PRIVACY_MODE="true"
 
 extract_plan_goal_content() {
     local plan_path="$1"
-    local goal_section=""
-
-    goal_section=$({ sed -n '/^##[[:space:]]*[Gg]oal\|^##[[:space:]]*[Oo]bjective\|^##[[:space:]]*[Pp]urpose/,/^##/p' "$plan_path" 2>/dev/null || true; } | head -20 | tail -n +2 | head -10)
+    local goal_section
+    goal_section=$(awk '
+        BEGIN { in_section = 0; emitted = 0 }
+        /^##[[:space:]]+/ {
+            lower = tolower($0)
+            if (in_section) {
+                exit
+            }
+            if (lower ~ /^##[[:space:]]*(goal|objective|purpose)([[:space:]]|$)/) {
+                in_section = 1
+            }
+            next
+        }
+        in_section {
+            if (emitted == 0 && $0 ~ /^[[:space:]]*$/) {
+                next
+            }
+            print
+            emitted++
+            if (emitted >= 10) {
+                exit
+            }
+        }
+    ' "$plan_path")
     if [[ -n "$goal_section" ]]; then
         printf '%s\n' "$goal_section"
         return
@@ -85,7 +106,29 @@ extract_plan_goal_content() {
 
 extract_plan_ac_content() {
     local plan_path="$1"
-    { sed -n '/^##[[:space:]]*[Aa]cceptance\|^##[[:space:]]*[Cc]riteria\|^##[[:space:]]*[Rr]equirements/,/^##/p' "$plan_path" 2>/dev/null || true; } | head -30 | tail -n +2 | head -25
+    awk '
+        BEGIN { in_section = 0; emitted = 0 }
+        /^##[[:space:]]+/ {
+            lower = tolower($0)
+            if (in_section) {
+                exit
+            }
+            if (lower ~ /^##[[:space:]]*(acceptance|criteria|requirements)([[:space:]]|$)/) {
+                in_section = 1
+            }
+            next
+        }
+        in_section {
+            if (emitted == 0 && $0 ~ /^[[:space:]]*$/) {
+                next
+            }
+            print
+            emitted++
+            if (emitted >= 25) {
+                exit
+            }
+        }
+    ' "$plan_path"
 }
 
 show_help() {
@@ -855,6 +898,61 @@ else
     cp "$FULL_PLAN_PATH" "$LOOP_DIR/plan.md"
 fi
 
+# Create an immutable context pack once per loop. Follow-up prompts reference this
+# stable file instead of re-embedding the full plan, which keeps reusable prompt
+# prefixes stable while preserving the original plan as the source of truth.
+CONTEXT_PACK_FILE="$LOOP_DIR/context-pack.md"
+CONTEXT_PACK_REL=".humanize/rlcr/$TIMESTAMP/context-pack.md"
+if command -v sha256sum >/dev/null 2>&1; then
+    PLAN_SHA256=$(sha256sum "$LOOP_DIR/plan.md" | awk '{print $1}')
+else
+    PLAN_SHA256=$(shasum -a 256 "$LOOP_DIR/plan.md" | awk '{print $1}')
+fi
+PLAN_GOAL_DIGEST=$(extract_plan_goal_content "$LOOP_DIR/plan.md")
+PLAN_AC_DIGEST=$(extract_plan_ac_content "$LOOP_DIR/plan.md")
+
+if [[ -z "$PLAN_GOAL_DIGEST" ]]; then
+    PLAN_GOAL_DIGEST="Use the original plan at $PLAN_FILE as the source of truth for the loop objective."
+fi
+
+if [[ -z "$PLAN_AC_DIGEST" ]]; then
+    PLAN_AC_DIGEST="- Acceptance criteria must be read from the original plan at $PLAN_FILE before implementation or review decisions."
+fi
+
+cat > "$CONTEXT_PACK_FILE" << EOF
+# RLCR Context Pack
+
+This file is generated once when the RLCR loop starts. Treat it as an immutable
+stable context prefix. If the plan evolves, record the change in goal-tracker.md
+or the current round contract instead of editing this file.
+
+## Source Identity
+
+- Plan file: $PLAN_FILE
+- Plan SHA256: $PLAN_SHA256
+- Project root: $PROJECT_ROOT
+- Start branch: $START_BRANCH
+- Base branch: $BASE_BRANCH
+- Base commit: $BASE_COMMIT
+
+## Goal Digest
+
+$PLAN_GOAL_DIGEST
+
+## Acceptance Criteria Digest
+
+$PLAN_AC_DIGEST
+
+## Source of Truth Rules
+
+- The original plan remains available at @$PLAN_FILE and is authoritative.
+- Use this context pack as the stable first read for routine re-anchoring.
+- Read the original plan whenever this digest is insufficient, ambiguous, or in conflict with code, summaries, reviews, or goal-tracker.md.
+- Full alignment reviews must read the original plan directly.
+- Deferrals are incomplete unless explicitly approved by the user and recorded in goal-tracker.md.
+EOF
+
+
 # Docs path default
 DOCS_PATH="docs"
 
@@ -904,6 +1002,7 @@ privacy_mode: $PRIVACY_MODE
 bitlesson_required: $BITLESSON_STATE_VALUE
 bitlesson_file: $BITLESSON_FILE_REL
 bitlesson_allow_empty_none: $BITLESSON_ALLOW_EMPTY_NONE
+context_pack_file: $CONTEXT_PACK_REL
 mainline_stall_count: 0
 last_mainline_verdict: unknown
 drift_status: normal
@@ -1299,7 +1398,7 @@ Read and execute below with ultrathink
 
 Before starting implementation, you MUST initialize the Goal Tracker:
 
-1. Read @$GOAL_TRACKER_FILE
+1. Read @$CONTEXT_PACK_REL, then read @$GOAL_TRACKER_FILE
 2. If the "Ultimate Goal" section says "[To be extracted...]", extract a clear goal statement from the plan
 3. If the "Acceptance Criteria" section says "[To be defined...]", define 3-7 specific, testable criteria
 4. Populate the "Active Tasks" table with MAINLINE tasks from the plan, mapping each to an AC and filling Tag/Owner
@@ -1322,6 +1421,14 @@ Use this contract to keep the round focused. Do NOT let non-blocking bugs or cle
 
 ---
 
+## Stable Context
+
+Read @$CONTEXT_PACK_REL first. The context pack is the stable digest for routine re-anchoring and prompt-cache reuse.
+
+The original full plan is still the source of truth at @$PLAN_FILE. Read the original plan whenever the context pack is insufficient, ambiguous, or conflicts with code, summaries, reviews, or goal-tracker.md.
+
+---
+
 ## Implementation Plan
 
 For all tasks that need to be completed, please use the Task system (TaskCreate, TaskUpdate, TaskList).
@@ -1348,8 +1455,6 @@ Each task must have one routing tag from the plan: \`coding\` or \`analyze\`.
 
 EOF
 
-# Append plan content directly (avoids command substitution size limits for large files)
-cat "$LOOP_DIR/plan.md" >> "$LOOP_DIR/round-0-prompt.md"
 
 # Append BitLesson Selection section
 cat >> "$LOOP_DIR/round-0-prompt.md" << EOF