Release 0.24.0: reusable Plan History and protected PR delivery

.github/workflows/ci.yml

@@ -0,0 +1,24 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+    types: [ready_for_review]
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  toolkit-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: '3.11'
+      - run: ./run-tests.sh
+      - run: sha256sum --check MANIFEST.sha256

MANIFEST.sha256

@@ -18,14 +18,15 @@ a3414533de88c12d4fedfd5c1311c505dc87364674cc8e599a982cacbe1620c6  ./.agent/plan-
 8c4e7fa9c1f9a84d5211c84c41cc20ed6a13a3ebc881bb175f1be6106db1fa85  ./.agent/plan-history/plan-summary.20260906T184718818166Z.101806a6188b911af737dd47187082418727ed7042831dd332d77360d1cb6b93.md
 a4d0bc13747cf250f25fb599b37f90cf519c95a29382f4da544afe9ff8095372  ./.agent/plan-history/plan-summary.20260907T162300226611Z.ddc507f2e3b9b24182cb6abc4eb4782feae98a0c25f8cdc174a2bf8c2c9932a1.md
 d60f352d0db1404c70afb4bb8b2ca3fd1c610572aa40720e8a0b7baa7885418c  ./.gitattributes
+13d683d7a117f01846724725f15a844768d16f52d226ec6d3f76143b1fc3f6f8  ./.github/workflows/ci.yml
 15cefba6945d22a52b5b8ef6dd656fffcb698627b9fb23dacc5c8ec27ad1680d  ./.gitignore
 6d7a25701ba2532525fe556f1a55529ab09af6675522f749afb22609f7f8183e  ./CODEX-INSTALL-PROMPT.md
 6612129aca01053f15098204fb4bbaafdf85a667956202530bdcbc339e58e462  ./LICENSE
 e4912f4f8d644555dcd57d5e336a249cf8a9d7f6222b78096d6b403f45a8a215  ./PLAYGROUND.md
-6eddb87e6d3e1e06141bbe43a88d112d9e1d017e6a365e7bba11e0da08988830  ./README.md
+964bddcb73a1cd9492eaf0340987a5f33aa57cad53f4ca62e4c73e984f82fa3f  ./README.md
 979191eeef7975567b4c44c9fb6dc38bf78e431eda582ff55d4f37eb2f69a441  ./THIRD_PARTY.md
 59b191889c8b7d098ddaf6b029f6f12b3ce6590893e1823f4448ad3b90c03fb4  ./assets/AGENTS.block.md
-90edd43aadb411c3e0fbd99593785c20339c8f1c9a52ae8b4b87a96f073875c4  ./assets/hooks/session_start.py
+b9f9eb58967f54b19fb3a58b1db32e4c25299ae10c06e2e45a6611c250801a71  ./assets/hooks/session_start.py
 3027ffa3ef382dcd0c96f6280ba861bb4a9410011e1176d71d7aa7911805821f  ./assets/runtime/repowise_bootstrap.py
 a564a3b00a86f43d38318b76168593bc965b2f1decf67a328d499a054aa35f36  ./assets/skills/adversarial-review/SKILL.md
 78443f93e9ee4861a0d7a110af7e6d5f1e7d736e1459324530eb584c6b08ba58  ./assets/skills/adversarial-review/references/finding-format.md
@@ -51,7 +52,7 @@ ac9ff3e77bb4958f6c7514c6ce7c4ca27e3638534bc8cd19753ea0f39f83e42e  ./assets/skill
 4acee4d97f68fc7b0d84e7fbe6f35d1e87b7a7f68c8bf624c2dcf79887623635  ./assets/skills/design-preflight/references/scope-boundaries.md
 cbe50a5f10a5adcf1725a7eddf56380ef8ac292e6fe32edfe069c5c02fdcc816  ./assets/skills/design-preflight/references/supported-model.md
 daafd85498937e8dd2914156fef193ea75e418d1ff49367e645d3c5bfcbe3b48  ./assets/skills/docs-maintainer/SKILL.md
-a9b148f2415583aaee2c8cd17822138e8ff8770670534b55a2e6ff2e4f1a936c  ./assets/skills/plan-history/SKILL.md
+8d9900474c986b5a9c18fda2a2444e65ecd20ada61edce9779a1018ea08ccf6a  ./assets/skills/plan-history/SKILL.md
 c67909e4aadda369b9550c09c5cc0311e3d86ef24f1965133eaf5cbdcbd84169  ./assets/skills/plan-history/agents/openai.yaml
 5ac5175efb1ee5fcd32b14d120361d148c0c2983095dc4d0dc90fa6e8a27b756  ./assets/skills/publication/SKILL.md
 a9bf1bbaa51743d53b8646c34c2f277660213fe9fbf3aeb2ede30c077667be1c  ./assets/skills/publication/references/publication.md
@@ -121,12 +122,14 @@ d8f7dfc833661cbd58913b85d334adb88e3ea9f1f337925a351fa113b814311f  ./docs/plans/c
 a2a2977403154705fc3d73fde0f45548c4722cc20b11cc189fe44f7982899224  ./docs/plans/cpk-055-native-ponytail.md
 8df1adc8b9063bc5035e6b91a95f39e3dd571be8db66cc4ab5161f7f16e4c879  ./docs/plans/cpk-056-interviews-and-assessment.md
 a5d8013da3d22afba28c1259e29e3255d1d19969d0934b2f59069f0de80ea31b  ./docs/plans/cpk-057-review-and-astra-guidance.md
-2fd92d860f05222ec7543cf8aff83ff9424acc51c7ca2c617a039b6e3f1156cf  ./docs/roadmap.md
+5f2abf3bc85fbfc580d05139165ff95f29a3a85246bab2724c5f949eb93f26a5  ./docs/plans/cpk-058-plan-history-compaction.md
+43141b61bf800dc9956603b6e88cdd0c3a5564340d3f4aee3fb6b0682dceee00  ./docs/plans/cpk-059-public-pr-release.md
+c14438f22cad4a83b4409a72e75b589d19440d20516511bd7d4a419b27deb7ed  ./docs/roadmap.md
 6f8f14ca5fd8ad935eee66256b3f7c49d5c40957eedff938ba21365e30869719  ./doctor.ps1
 ab56a88d9188979f06ea142d1f58ea0d6ad9088e83a965bd324209d83da513ad  ./doctor.sh
 8087bdb3ee654c0baac278a8e3bf85e33e314f8acfd486e7ebf675126a697058  ./install.ps1
 3466d2e34145cfdaa83d793960794b2aefc96f3d9c48d22fd2af930ec819e9c4  ./install.sh
-bc43e00be4e0adbb58a444f329cc9f6327b5d4ec2a00259f82bbc9e4820f7f77  ./kit.py
+7843fa0b49e088495e603e8eb3ae6811cb40007d7b40bf3e621f7855d1722159  ./kit.py
 331f17ca1486b5779d9b57a3a73834328eb3089ce612e636e6a8e5085899d61e  ./run-tests.ps1
 e6df9f1da02280a66161583529b06a34f0103041e9587afad0fac6074eecc15b  ./run-tests.sh
 85a2ba72e2b0cd1ab6c25a51f39059502415c3ac62a6bffa613d7e31b6422cd4  ./setup-repo.ps1
@@ -137,7 +140,7 @@ e1e231aac51822f7e1bb3aa61aba138cf8c5df9cefd3079b0c1b5a98eea03bd9  ./tests/fixtur
 a269775204ae7cad2457d00f5565c90da2df41a9719479f3489ec01afdd2519c  ./tests/fixtures/cpk056-agent-cases.json
 e32941eb74be1f2cdcb6c82cf71e113b841651bf0d01786f364176de2da1b9c5  ./tests/fixtures/cpk056-agent-grading.json
 289367b7090a0d71936b41f08c4a354bc2758013dceb709819de36a1b73d9aa6  ./tests/live_plan_history.py
-a752cb4eb2a58614ab988106a83e9263bba3f30da9fb0f55bcd1a17375fcd1b9  ./tests/test_kit.py
+74d96d387c814f60e37f0ba682bb42e1ba05b729c866b929d026166a4a9be4c9  ./tests/test_kit.py
 cfa479b5248a628ecd71194b7ac4a36bcddf17af7eb52ca2a6c3cd0566269927  ./tests/test_ponytail.py
 d16f7eadc8c668e82a1d0d2554ed04def15cb0a4b2ce13ac1ce1339bc0e62161  ./uninstall.ps1
 f12cff94ef7f9b0ca489cbe43e1de737011476966e04c1578f4977177b0da217  ./uninstall.sh

README.md

@@ -72,6 +72,8 @@ The edit hooks update `<primary-checkout>/.codex/roadmap-view.md` after an agent
 
 The [Plan history skill](assets/skills/plan-history/SKILL.md) keeps repository summaries versioned in `.agent/plan-history/`. Specification associations stay in each record. Later planning sessions find these records across worktrees and reconcile their decisions.
 
+For large histories, agents create reusable reading summaries under `.agent/plan-history/compacted/`. Original records remain unchanged. The skill also preserves reading progress across normal context compaction.
+
 An unrecorded destination skill is a conflict. The installer stops before it changes that directory.
 
 Open a new Codex session after installation. Use `/hooks` to review and trust the toolkit and Ponytail commands.
@@ -264,6 +266,12 @@ Repository-owned `AGENTS.md`, `.agent/PLANS.md`, roadmaps, and other project doc
 
 Remove the toolkit source checkout or downloaded archive only when you no longer need it. Leave unrelated Codex configuration and other plugins intact.
 
+## Contributing
+
+Changes use draft pull requests and Codex review before readiness. The required `toolkit-tests` check runs when a PR becomes ready and after pushes to `main`. It runs the toolkit tests and verifies distribution checksums.
+
+Protected `main` requires a pull request, passing CI, and resolved conversations. Codex review is a separate publication gate; no additional human approval is required. Follow the [publication procedure](assets/skills/publication/references/publication.md).
+
 ## Verification
 
 On macOS or Linux, run:

assets/hooks/session_start.py

@@ -390,7 +390,7 @@ def save_transcript_plan(event: dict[str, object]) -> list[str]:
     warnings = save_transcript_plan(event)
     context = "Codex Practical Kit is active. Read the managed AGENTS.md links that apply to this task."
     if event.get("source") == "compact":
-        context += " Apply repository-knowledge before the next repository lookup. Keep it active until the task ends. Before later planning, use plan-history and reconcile all applicable records."
+        context += " Apply repository-knowledge before the next repository lookup. Keep it active until the task ends. Use plan-history to resume saved reconciliation after compaction."
     if warnings:
         context += " Plan history warning: " + "; ".join(warnings)
     print(json.dumps({

assets/skills/plan-history/SKILL.md

@@ -8,7 +8,8 @@ description: >
 ---
 
 <!-- cpk-rule-owner: plan-history -->
-<!-- cpk-rule-guard: Read every applicable Plan history record before later planning. -->
+<!-- cpk-rule-guard: Account for every applicable Plan history record before later planning. -->
+<!-- cpk-rule-guard: Context size and ordinary context compaction never require a history-reading stop. -->
 <!-- cpk-rule-guard: A completed Plan Mode response declares every known related specification or explicitly declares none. -->
 <!-- cpk-rule-guard: Stop planning when retained decisions conflict without a recorded supersession. -->
 <!-- cpk-rule-guard: Save a completed Plan before the next submitted prompt continues. -->
@@ -31,17 +32,62 @@ Specification markers in the saved response retain its associations. Do not crea
 
 Apply [Repository knowledge](../repository-knowledge/SKILL.md) first. Use RepoWise to identify the repository, task, ExecPlan, and related specifications.
 
-Read every applicable Plan history record before later planning.
+Account for every applicable Plan history record before later planning. Read original records or reuse verified summaries through the procedure below.
 
-Then enumerate files directly. In a Git repository, use `git worktree list --porcelain -z` to find every worktree. Read every file in `.agent/plan-history/` in each worktree. For each identified specification, also read legacy siblings named `<spec-stem>.plan-summary.*.md` in those worktrees. Also inspect the current global fallback directory when the prompt identifies a prior storage warning.
+Then enumerate files directly. In a Git repository, use `git worktree list --porcelain -z` to find every worktree. Inventory every original record in `.agent/plan-history/` in each worktree. Enumerate `compacted/*.md` separately; these derived summaries are not original captures. For each identified specification, also read legacy siblings named `<spec-stem>.plan-summary.*.md` in those worktrees. Also inspect the current global fallback directory when the prompt identifies a prior storage warning.
 
 Use the same discovery before implementation when the user resumes or implements a plan after context was cleared.
 
 Resume from the ExecPlan specification, applicable Plan history, roadmap state, the Git worktree and completed checkpoint history, the ignored task result when it exists, and the current conversation when available. Do not infer operational status from the ExecPlan.
 
-Do not trust a RepoWise match limit or index freshness as proof that no record exists. Do not select the first match. Deduplicate only records with the same event key and identical bytes. Retain and reconcile every distinct-content collision record. Read each unique record completely.
+Do not trust a RepoWise match limit or index freshness as proof that no record exists. Do not select the first match. Deduplicate only records with the same event key and identical bytes. Retain and reconcile every distinct-content collision record. Record each original's path, event key, filename timestamp, and SHA-256 of its complete bytes. Keep path aliases for identical copies across worktrees.
 
-If the complete applicable set cannot fit in context, stop. List every unread path. Do not continue with partial history.
+Context size and ordinary context compaction never require a history-reading stop. Process history in bounded reads, including chunks within one large record. Complete reconciliation before planning continues; the raw history need not fit in one context window.
+
+## Reusable summaries
+
+Keep derived summaries in `.agent/plan-history/compacted/<topic>.<UTC>.md`, versioned with the task. Outside Git, use `compacted/` under the existing global fallback directory. Never overwrite a summary revision. Create a new file when its content changes. Keep original captures unchanged and retain their last copies.
+
+A summary is a reading aid, not a new specification, accepted decision, or task-status record. Its scope identifies the topics and specification associations it covers. A new task can reuse it within that scope. A broader task must reopen the original evidence for the added scope.
+
+Each summary contains:
+
+- `Scope`: covered topics, specification associations, and explicit exclusions.
+- `Sources`: original paths, event keys, filename timestamps, complete-byte SHA-256 hashes, and source anchors for the decisions.
+- `Decisions`: requirements, constraints, acceptance criteria, rejected options, and reasons within that scope, attributed to their originals.
+- `Supersessions`: the original record, reason, replacement, and exact scope; retain carried decisions outside that scope.
+- `Conflicts`: unresolved questions and conflicting decisions, with both original sources. Use an explicit `none` when absent.
+- `Verification`: which complete originals were read and compared with the summary, including their hashes. Include the paths and hashes of any separate supersession evidence.
+
+Read each uncovered original completely before certifying its summary coverage. Compare the draft against each original while that source is available. Preserve every decision within the declared scope. A SHA-256 match proves byte identity, not semantic fidelity. Do not certify a summary from a filename, partial read, or another summary alone.
+
+Keep summaries small enough to read in batches. Split them by source or topic when needed, retaining direct original references in every part. Do not build chains of summaries of summaries. Read a large summary in chunks and retain its relevant decisions outside conversation context.
+
+Before reuse, compare the current inventory with each summary's source identities and hashes. Check its scope and verification record. Read and reconcile new, uncovered, changed, or distinct-content records. A summary cannot prove that no newer record exists.
+
+If summary evidence is missing, stale, incomplete, or inconsistent, reread the affected originals and create corrected derived evidence. Reuse unaffected verified summaries. If summaries disagree, inspect their originals before treating the disagreement as a decision conflict. Original evidence takes precedence.
+
+Use original filename timestamps for reconciliation, not summary creation times. Apply the conflict and supersession rules below across all batches and summaries. A newer summary cannot authorize a replacement decision.
+
+## Bounded reads and resumption
+
+Keep reading progress in the existing ignored `.agent/test-results/<task>.md` working record, outside the reusable summaries. Outside Git, use an untracked working file beside the fallback history. Save a checkpoint before long reads and after each completed chunk or batch. Include:
+
+- The task scope and complete source inventory, including identities, hashes, and any aliases.
+- Reused summary paths and hashes, with their verified coverage.
+- Completed records, pending records, and the next source range to read.
+- For a partial record: its complete-byte hash, consumed ranges, and provisional decisions. Do not mark that record complete.
+- Retained decisions, source anchors, unresolved conflicts, and supersession evidence needed to reconcile later batches.
+
+After ordinary context compaction, resume this checkpoint through Plan History. Validate the saved source and summary hashes, then continue from the first unaccounted range. A context reset does not invalidate verified coverage. Do not restart all raw reads merely because their text left the context window.
+
+If the checkpoint is absent or incomplete, reconstruct coverage from verified reusable summaries. Reread only evidence whose coverage or retained decisions cannot be established. If a partially read source changed, reread that source from its beginning. Preserve unaffected coverage.
+
+Partition a large reconciliation by topic or decision owner. Keep cross-topic references and outstanding comparisons in the working record. Do not discard unresolved decisions to meet a context budget.
+
+Before declaring reconciliation complete, enumerate the original inventory again and account for every addition or change. Every applicable original must have complete direct-read coverage or verified summary coverage for this task's scope. Empty history needs no summary. Continue reading while coverage is incomplete; do not emit a plan based on an unread tail.
+
+An actually unreadable required source or an unresolved source-backed decision conflict remains a blocker. Report the exact source and reason. Context compaction alone is neither failure nor evidence of a conflict.
 
 ## Reconcile decisions
 
@@ -60,7 +106,7 @@ Stop planning when retained decisions conflict without a recorded supersession.
 
 ## Replan checkpointed work
 
-Before a replan, read the current ExecPlan, every applicable Plan record, and the completed checkpoint history in Git.
+Before a replan, read the current ExecPlan and completed checkpoint history in Git. Account for every applicable Plan record through the reading and summary procedure above.
 
 Keep accepted contracts unchanged. Use completed checkpoint history in Git as immutable operational evidence. Split, merge, reorder, or replace only unfinished subtasks. Never amend or rewrite a completed checkpoint commit.
 
@@ -88,7 +134,7 @@ Do not omit the marker. Do not use an absolute path or a path outside the reposi
 
 ## Implementation handoff
 
-Link every applicable record from the task ExecPlan. Treat each linked decision as an implementation constraint.
+Link every applicable original record from the task ExecPlan. Summary links are supplemental; they do not replace original links. Treat each linked decision as an implementation constraint.
 
 Relocate applicable untracked Plan records to the task worktree before task edits.