diff --git a/.agent/PLANS.md b/.agent/PLANS.md index dd621f4..d030aa7 100644 --- a/.agent/PLANS.md +++ b/.agent/PLANS.md @@ -2,188 +2,51 @@ -# Codex Execution Plans (ExecPlans): +# Codex Execution Plans (ExecPlans) -This document describes the requirements for an execution plan ("ExecPlan"), a design document that a coding agent can follow to deliver a working feature or system change. Treat the reader as a complete beginner to this repository: they have only the current working tree and the single ExecPlan file you provide. There is no memory of prior plans and no external context. -## How to use ExecPlans and PLANS.md +An ExecPlan is the only durable implementation plan for a task. Use one for complex features, multi-file changes, and significant refactors. Skip it for a small isolated change. -An ExecPlan is the only durable implementation plan for a task. Use one for complex features, multi-file changes, and significant refactors. Do not create a plan file for a small, isolated change. +Use repository `.agent/PLANS.md` when it exists. Otherwise, use toolkit-managed `$CODEX_HOME/PLANS.md`. Store the current task specification in `docs/plans/`, with its roadmap identifier in the filename. -Use the repository's `.agent/PLANS.md` when it exists. Otherwise, use the toolkit-managed `$CODEX_HOME/PLANS.md`. Store the task ExecPlan in `docs/plans/`. Use the roadmap identifier in its filename when the task has one. +Merge accepted Plan Mode and Design Preflight decisions into that specification. Apply `plan-history` to reconcile current evidence. Keep no second mutable brief or plan. Link current rules instead of copying them. -Plan Mode and Design Preflight are preparation stages. Merge their accepted decisions into the ExecPlan. Do not preserve a second mutable plan, brief, or preflight record for the same task. Immutable Plan Mode summaries are source records, not implementation plans. Apply the `plan-history` skill. The ExecPlan owns stable decisions, scope, instructions, design-shaping discoveries, and final product outcomes. +## Specification content -When authoring an executable specification (ExecPlan), follow PLANS.md _to the letter_. If it is not in your context, refresh your memory by reading the entire PLANS.md file. Be thorough in reading (and re-reading) source material to produce an accurate specification. When creating a spec, start from the skeleton and flesh it out as you do your research. -When implementing an ExecPlan, proceed through its milestones. Update it only when a durable decision, scope boundary, instruction, design-shaping discovery, or final product outcome changes. +An ExecPlan is a living specification until review closure. Keep it concise and self-contained. A new contributor must understand the required outcome, owners, boundaries, edits, and proof from this file and its named current sources. -Do not record operational progress or results in an ExecPlan. +Start with the visible outcome and how to observe it. State the repository-relative paths, entry points, state owners, commands, expected results, and dependencies needed to implement it. Define unfamiliar terms in plain English. Keep only current instructions and decisions. -Do not write a readiness or authorization statement in an ExecPlan. +Record the Git base, task branch or worktree, product boundary, supported model, and accepted Scenario Proof. Give every authoritative source clause an explicit disposition when Design Preflight requires it. Link the relevant focused owners. -Record task-specific facts and accepted decisions. Link applicable toolkit rules instead of copying them into the plan. +Include a `Decision Log` with each retained decision and its reason. Replace obsolete alternatives when they no longer explain a current choice. Include discoveries only when they change the design. Do not duplicate source transcripts or a historical decision inventory. -Record the accepted product boundary facts and owner classifications from Design Preflight. Link its Scope boundaries owner. +Do not record operational progress or results in an ExecPlan. Do not write a readiness or authorization statement. To resume, also inspect the roadmap, Git checkpoint history, applicable current decisions, active task evidence, and conversation. -When discussing an executable specification (ExecPlan), record decisions in its log. State why each specification change occurred. An ExecPlan is a living specification until review closure. It must remain self-contained as a specification. To resume work, also inspect applicable Plan history, roadmap state, the Git worktree and checkpoint history, the ignored task result when it exists, and the current conversation when available. +Use prose-first Markdown with two newlines after headings. Use indented commands instead of nested fences. A standalone Markdown file needs no enclosing code fence. In chat, use one `md` fence when returning the complete specification. -When researching a design with challenging requirements or significant unknowns, use milestones to implement proof of concepts, "toy implementations", etc., that allow validating whether the user's proposal is feasible. Read the source code of libraries by finding or acquiring them, research deeply, and include prototypes to guide a fuller implementation. +## Subtasks and proof -## Lifecycle rule - -[Delivery lifecycle](<../assets/skills/delivery-lifecycle/references/delivery-lifecycle.md>) - -## Requirements - -NON-NEGOTIABLE REQUIREMENTS: - -* Every ExecPlan must be fully self-contained. Self-contained means that in its current form it contains all knowledge and instructions needed for a novice to succeed. -* Every ExecPlan is a living specification until review closure. Revise it only when a durable decision, scope boundary, instruction, design-shaping discovery, or final product outcome changes. Each revision must remain fully self-contained. -* Every ExecPlan must enable a complete novice to implement the feature end-to-end without prior knowledge of this repo. -* Every ExecPlan must produce a demonstrably working behavior, not merely code changes to "meet a definition". -* Every ExecPlan must define every term of art in plain language or do not use it. - -Purpose and intent come first. Begin by explaining, in a few sentences, why the work matters from a user's perspective: what someone can do after this change that they could not do before, and how to see it working. Then guide the reader through the exact steps to achieve that outcome, including what to edit, what to run, and what they should observe. - -The agent executing your plan can list files, read files, search, run the project, and run tests. It does not know any prior context and cannot infer what you meant from earlier milestones. Repeat any assumption you rely on. Do not point to external blogs or docs; if knowledge is required, embed it in the plan itself in your own words. If an ExecPlan builds upon a prior ExecPlan and that file is checked in, incorporate it by reference. If it is not, you must include all relevant context from that plan. - -## Formatting - -Format and envelope are simple and strict. Each ExecPlan must be one single fenced code block labeled as `md` that begins and ends with triple backticks. Do not nest additional triple-backtick code fences inside; when you need to show commands, transcripts, diffs, or code, present them as indented blocks within that single fence. Use indentation for clarity rather than code fences inside an ExecPlan to avoid prematurely closing the ExecPlan's code fence. Use two newlines after every heading, use # and ## and so on, and correct syntax for ordered and unordered lists. - -When writing an ExecPlan to a Markdown (.md) file where the content of the file *is only* the single ExecPlan, you should omit the triple backticks. - -Write in plain prose. Prefer sentences over lists. Do not use checklists for task status. Use tables or long enumerations only when brevity would obscure meaning. Narrative sections must remain prose-first. - -## Guidelines - -Self-containment and plain language are paramount. If you introduce a phrase that is not ordinary English ("daemon", "middleware", "RPC gateway", "filter graph"), define it immediately and remind the reader how it manifests in this repository (for example, by naming the files or commands where it appears). Do not say "as defined previously" or "according to the architecture doc." Include the needed explanation here, even if you repeat yourself. - -Avoid common failure modes. Do not rely on undefined jargon. Do not describe "the letter of a feature" so narrowly that the resulting code compiles but does nothing meaningful. Do not outsource key decisions to the reader. When ambiguity exists, resolve it in the plan itself and explain why you chose that path. Err on the side of over-explaining user-visible effects and under-specifying incidental implementation details. - -Anchor the plan with observable outcomes. State what the user can do after implementation, the commands to run, and the outputs they should see. Acceptance should be phrased as behavior a human can verify ("after starting the server, navigating to [http://localhost:8080/health](http://localhost:8080/health) returns HTTP 200 with body OK") rather than internal attributes ("added a HealthCheck struct"). If a change is internal, explain how its impact can still be demonstrated (for example, by running tests that fail before and pass after, and by showing a scenario that uses the new behavior). - -Specify repository context explicitly. Name files with full repository-relative paths, name functions and modules precisely, and describe where new files should be created. If touching multiple areas, include a short orientation paragraph that explains how those parts fit together so a novice can navigate confidently. When running commands, show the working directory and exact command line. When outcomes depend on environment, state the assumptions and provide alternatives when reasonable. - -Record the accepted supported operating model. Link the applicable rule owner and state task-specific inclusions or exclusions. - -Record the accepted product boundary source and relevant owner classifications. - -For non-trivial runtime behavior, include the accepted Scenario Proof. Link its focused rule owners and record only the task-specific cases and checks. - -Validation is not optional. Include instructions to run tests, to start the system if applicable, and to observe it doing something useful. Describe comprehensive testing for any new features or capabilities. Include expected outputs and error messages so a novice can tell success from failure. Where possible, show how to prove that the change is effective beyond compilation (for example, through a small end-to-end scenario, a CLI invocation, or an HTTP request/response transcript). State the exact test commands appropriate to the project’s toolchain and how to interpret their results. - -Capture evidence. When your steps produce terminal output, short diffs, or logs, include them inside the single fenced block as indented examples. Keep them concise and focused on what proves success. If you need to include a patch, prefer file-scoped diffs or small excerpts that a reader can recreate by following your instructions rather than pasting large blobs. - -## Milestones - -Milestones are narrative, not bureaucracy. If you break the work into milestones, introduce each with a brief paragraph that describes the scope, what will exist at the end of the milestone that did not exist before, the commands to run, and the acceptance you expect to observe. Keep it readable as a story: goal, work, result, proof. Never abbreviate a milestone merely for the sake of brevity, and do not leave out details that could be crucial to a future implementation. - -Each milestone must be independently verifiable and incrementally implement the overall goal of the execution plan. - -### Semantic subtasks and checkpoint boundaries - -Split an ExecPlan at semantic proof boundaries, not at a numeric action limit. - -Use multiple ordered subtasks when the work has outcomes that can remain valid and receive separate proof. Separate user-visible outcomes and primary code owners when they can change independently. Separate a foundation from its consumers when the foundation has a useful, verifiable contract. Separate a migration from later adoption when each stage can leave the product valid. Separate an interface from later consumers when the interface can remain valid by itself. - -Keep one subtask when an atomic migration or one stateful sequence needs one proof boundary. Do not split work by an action count. Do not use a numeric action limit. - -Use one ExecPlan for the task. Do not create child ExecPlans. Give each subtask a stable identifier. Do not renumber a completed subtask. - -For each subtask, state its observable outcome and primary owner. State the allowed change boundary and its dependencies on earlier subtasks. Give the exact validation command and required oracle. State the checkpoint review boundary and local commit boundary. - -Complete each subtask with its focused validation and checkpoint review before its planned local commit. Keep the roadmap task active between checkpoints. After all subtasks are complete, run one final review of the complete task. - -## Living plans and design decisions +Split an ExecPlan at semantic proof boundaries, not at a numeric action limit. Do not use a numeric action limit. Separate user-visible outcomes and primary code owners when their results can remain useful independently. Separate a foundation from its consumers, a migration from later adoption, or an interface from later consumers when each has a valid independent result. -* Before review closure, update the plan when you make a key design decision. Record the decision and its rationale in the `Decision Log` section. -* ExecPlans must contain a `Decision Log`. Add `Surprises & Discoveries` only for evidence that changes the design. Add `Outcomes & Retrospective` only for final product outcomes, not operational status. -* When you discover optimizer behavior, performance tradeoffs, unexpected bugs, or inverse/unapply semantics that shaped your approach, capture those observations in the `Surprises & Discoveries` section with short evidence snippets (test output is ideal). -* If you change course mid-implementation, document why in the `Decision Log` and revise the stable implementation instructions. Plans are guides for the next contributor, not task-status ledgers. -* At completion, an `Outcomes & Retrospective` entry can summarize the observable product outcome and design lessons. Do not include test, review, checkpoint, commit, or delivery status. -* Do not rewrite completed ExecPlans or immutable Plan history merely to remove historical status content. Apply this contract when an active or resumed plan is next edited. +Keep one subtask for an atomic migration or one stateful sequence that needs one proof boundary. Use one ExecPlan, without child plans. Give each subtask a stable identifier. Do not renumber a completed subtask. -# Prototyping milestones and parallel implementations +For each subtask, state its observable outcome, primary owner, allowed change boundary, dependencies on earlier subtasks, exact validation command and required oracle, checkpoint review boundary and local commit boundary. -It is acceptable—-and often encouraged—-to include explicit prototyping milestones when they de-risk a larger change. Examples: adding a low-level operator to a dependency to validate feasibility, or exploring two composition orders while measuring optimizer effects. Keep prototypes additive and testable. Clearly label the scope as “prototyping”; describe how to run and observe results; and state the criteria for promoting or discarding the prototype. +Specify runnable checks with concrete inputs and expected terminal outcomes. Include relevant failure distinctions. A suite pass does not replace a named scenario's proof. Keep ordinary logs and results in the active task evidence. -Prefer additive code changes followed by subtractions that keep tests passing. Parallel implementations (e.g., keeping an adapter alongside an older path during migration) are fine when they reduce risk or enable tests to continue passing during a large migration. Describe how to validate both paths and how to retire one safely with tests. When working with multiple new libraries or feature areas, consider creating spikes that evaluate the feasibility of these features _independently_ of one another, proving that the external library performs as expected and implements the features we need in isolation. +Complete each subtask's validation and checkpoint review before its local commit. A sequence of reviewed checkpoints ends with one final review of the complete task. One atomic subtask can use a single full review. -## Skeleton of a Good ExecPlan +## Revisions and useful lifetime - # - This ExecPlan is a living specification until review closure. Keep durable decisions, scope, instructions, and design-shaping discoveries current until then. +Revise this specification when an accepted requirement, boundary, design decision, or instruction changes. Keep all sections consistent and state the reason in the Decision Log. Git owns prior versions. - If PLANS.md file is checked into the repo, reference the path to that file here from the repository root and note that this document must be maintained in accordance with PLANS.md. +Keep a completed plan only while a current task, pending integration, or maintained product specification still uses it. Put lasting product facts in their existing authoritative document. Use a direct Git reference for a needed historical source. - ## Purpose / Big Picture +## Lifecycle and cleanup - Explain in a few sentences what someone gains after this change and how they can see it working. State the user-visible behavior you will enable. - - ## Surprises & Discoveries - - Document only unexpected behaviors, bugs, optimizations, or insights that change the design. Provide concise evidence. - - - Observation: … - Evidence: … - - ## Decision Log - - Record every decision made while working on the plan in the format: - - - Decision: … - Rationale: … - - ## Outcomes & Retrospective - - Summarize the final observable product outcome and design lessons. Do not record operational status. - - ## Context and Orientation - - Describe the current state relevant to this task as if the reader knows nothing. Name the key files and modules by full path. Define any non-obvious term you will use. Do not refer to prior plans. - - ## Product Boundary - - Link the applicable Scope boundaries owner. Record the authoritative product source, current production use cases, relevant owner classifications, and resolved specification conflicts. - - ## Scenario Proof - - For non-trivial runtime behavior, link the accepted Scenario Proof rules. Record the task-specific cases, expected results, owners, and runnable checks. - - ## Plan of Work - - Describe, in prose, the sequence of edits and additions. For each edit, name the file and location (function, module) and what to insert or change. Keep it concrete and minimal. - - ## Concrete Steps - - State the exact commands to run and where to run them (working directory). When a command generates output, show a short expected transcript so the reader can compare. - - ## Validation and Acceptance - - Describe how to start or exercise the system and what to observe. Phrase acceptance as behavior, with specific inputs and outputs. If tests are involved, say "run and expect passed; the new test fails before the change and passes after>". - - ## Idempotence and Recovery - - State whether normal steps can be repeated. If a command fails, stop and report it unless the task explicitly defines recovery. - - ## Artifacts and Notes - - Include only design-shaping transcripts, diffs, or snippets as indented examples. Keep ordinary validation and review results in the ignored task record. - - ## Interfaces and Dependencies - - Be prescriptive. Name the libraries, modules, and services to use and why. Specify the types, traits/interfaces, and function signatures that must exist at the end of the milestone. Prefer stable names and paths such as `crate::module::function` or `package.submodule.Interface`. E.g.: - - In crates/foo/planner.rs, define: - - pub trait Planner { - fn plan(&self, observed: &Observed) -> Vec; - } - -If you follow the guidance above, a single, stateless agent -- or a human novice -- can read your ExecPlan from top to bottom and produce a working, observable result. That is the bar: SELF-CONTAINED, SELF-SUFFICIENT, NOVICE-GUIDING, OUTCOME-FOCUSED. - -Before review closure, make sure that each revision is consistent across all sections. Add a final note that describes the change and its reason. ExecPlans must describe the work and the reason for it. + +[Delivery lifecycle](../assets/skills/delivery-lifecycle/references/delivery-lifecycle.md) diff --git a/.agent/plan-history/plan-summary.20260819T195712262086Z.manual-recovery.md b/.agent/plan-history/plan-summary.20260819T195712262086Z.manual-recovery.md deleted file mode 100644 index 9e82771..0000000 --- a/.agent/plan-history/plan-summary.20260819T195712262086Z.manual-recovery.md +++ /dev/null @@ -1,41 +0,0 @@ - -# Shared Roadmap View - -## Summary - -Keep `docs/roadmap.md` authoritative in each active task worktree. Generate a stable, read-only view at `/.codex/roadmap-view.md` after an actual roadmap edit. - -The view will never initialize from `SessionStart`. This prevents a stale worktree from becoming authoritative merely because a session opened there. - -## Implementation - -- Create roadmap item `CPK-038` and `docs/plans/cpk-038-shared-roadmap-view.md`. Reconcile this Plan history into that ExecPlan before implementation. -- Extend the existing hook runtime with managed `PreToolUse` and `PostToolUse` entries matching `^apply_patch$`. The [official hook contract](https://learn.chatgpt.com/docs/hooks) supplies `cwd`, `tool_use_id`, and `tool_input.command`. -- Before an exact `docs/roadmap.md` operation, record its content fingerprint by `tool_use_id`. Afterward, refresh the view only if the source changed. This prevents failed or no-op patches from publishing stale content. -- Scan every `Add File` and `Update File` operation. Normalize paths against `cwd` and accept only the active worktree’s exact roadmap path. -- Resolve the primary checkout through the shared Git directory. Write an ownership marker, a visible generated-file warning, and the active worktree’s roadmap content. -- Check for a user-owned destination before changing `.git/info/exclude`. Preserve and warn on collisions. Otherwise, add a marked exact exclusion for `/.codex/roadmap-view.md`. -- Keep successful synchronization silent. Return one nonblocking `systemMessage` for applicable Git or file failures. -- Restrict `additionalContextLimit` to hooks that emit additional context. Do not add it to `PreToolUse`, `PostToolUse`, or `Stop`. -- Make `remove-repo` delete only toolkit-owned views and exclusion blocks. Global uninstall will intentionally leave repository-local projections because it cannot safely enumerate every repository. -- Update the roadmap-maintainer rule and user documentation: agents edit only `docs/roadmap.md`; users may keep `.codex/roadmap-view.md` open. - -## Test Plan - -- Create and refresh the view from primary and linked-worktree roadmap changes. -- Cover a newly added roadmap, multiple patch operations, and a valid target after a lookalike path. -- Reject nested, unrelated, malformed, failed, and no-op roadmap operations without changing the view. -- Verify a stale worktree session or unrelated edit cannot roll the view backward. -- Preserve user-owned destination files, exclusion contents, and Git-status visibility. -- Verify generated state remains untracked and source roadmaps remain untouched. -- Exercise install, reinstall, `remove-repo`, and global uninstall while preserving unrelated hooks. -- Confirm repositories without a roadmap receive no generated files or Git exclusions. - -## Assumptions - -- Agent roadmap edits use `apply_patch`, as required by the toolkit. -- Simultaneous roadmap writers, manual edits, deletion or rename synchronization, symlinked layouts, submodules, and bare repositories remain outside this change. -- The generated view first appears after the next successful roadmap edit. - - - diff --git a/.agent/plan-history/plan-summary.20260819T211423672232Z.manual-recovery.md b/.agent/plan-history/plan-summary.20260819T211423672232Z.manual-recovery.md deleted file mode 100644 index d4f9d16..0000000 --- a/.agent/plan-history/plan-summary.20260819T211423672232Z.manual-recovery.md +++ /dev/null @@ -1,70 +0,0 @@ - -# CPK-039 — Native Windows Compatibility - -## Summary - -Add native Windows 10/11 support through PowerShell 7 while preserving existing macOS/Linux behavior. Use five thin `.ps1` launchers and one cross-platform Python RepoWise bootstrap. Do not add batch files, PowerShell 5.1 support, Windows CI, or duplicate runtime implementations. - -Base `cpk-039-native-windows` on completed CPK-038 commit `66a8db7`. Create the CPK-039 ExecPlan, preserve this Plan Mode summary beside it, and make CPK-039 the sole active roadmap task. - -## Implementation - -- Add `install.ps1`, `uninstall.ps1`, `setup-repo.ps1`, `doctor.ps1`, and `run-tests.ps1`. - - Require PowerShell 7. - - Resolve `kit.py` through `$PSScriptRoot`. - - Forward arguments without string reparsing. - - Propagate Python exit codes. - - Make `run-tests.ps1` stop after failed tests; otherwise compile `kit.py` and every hook Python file. -- Add minimal platform selection to `kit.py`. - - Discover `uv.exe` and `repowise.exe` on Windows. - - Keep existing POSIX discovery and installation behavior. - - Install missing Windows uv through the pinned official `install.ps1`, verify its SHA-256, and execute it once through `pwsh` stdin with process-scoped execution-policy bypass. - - Install missing RepoWise through the resolved uv executable. -- Replace the embedded shell MCP bootstrap with one installed standard-library Python script. - - Configure MCP with `sys.executable` and argument-array paths; preserve unrelated TOML and existing hook `commandWindows` entries. - - In Git repositories: initialize RepoWise when absent, install its hook every start, update only when `HEAD` exists, start and check the watcher, then start MCP. - - Initialize Git only when the current non-Git directory is completely empty. Do not mutate non-empty non-Git directories. - - Send setup diagnostics to stderr. Reserve stdout for RepoWise MCP. - - On POSIX, retain the shebang-derived Python watcher and read-event filter. - - On Windows, invoke `repowise.exe watch` directly. - - If the watcher exits during readiness, return failure without starting MCP. Always terminate and wait for a live watcher after MCP exits. -- Preserve existing uninstall ownership. - - Normal uninstall removes active integrations, copied skills, global Plans, owned configuration blocks, and the manifest. - - It retains the source checkout, managed install root, bootstrap, uv, RepoWise, and Plan history. - - `--purge` additionally removes the managed install root. -- Update README, install prompt, RepoWise documentation, publication instructions, manifest, upstream lock, and version surfaces to `0.19.0`. Publication must select `.ps1` on Windows and `.sh` on POSIX. - -## Verification - -- Add focused tests for: - - The complete five-launcher inventory and manifest coverage of every new launcher and bootstrap asset. - - Argument and exit-code propagation, including paths containing spaces. - - `run-tests.ps1` success and short-circuit behavior. - - Independent Windows cases for existing executables, missing uv, and missing RepoWise. - - Exact Windows and POSIX watcher command arrays. - - Ordered first-start, repeat-start, no-`HEAD`, empty-directory, and non-empty non-Git lifecycles. - - Watcher readiness failure, prevention of MCP startup, cleanup, and stdout/stderr ownership. - - TOML preservation, Doctor readiness, normal uninstall, purge, version, checksums, and lock contents. - - Full POSIX regression coverage. -- PowerShell tests may skip locally when `pwsh` is unavailable. Native Windows validation remains mandatory. -- Freeze implementation, documentation, manifest, lock, and validation instructions; then commit and push the checkpoint. -- Give the user this VM checkout command: - - ```powershell - gh repo clone calculatetech/codex-practical-kit codex-practical-kit-cpk-039 -- --branch cpk-039-native-windows --single-branch - ``` - -- In the native VM, run `run-tests.ps1`, install, repository setup, Doctor, and both uninstall modes. Start a fresh Codex session in the prepared repository, confirm RepoWise initializes, successfully execute a RepoWise lookup, and retain watcher/MCP evidence. -- Record the exact tested commit and VM result in `.agent/test-results/cpk-039-native-windows.md`. -- Any later change affecting Windows commands, installed artifacts, checksums, configuration generation, or the validation procedure requires a new pushed checkpoint and repeated affected VM checks. -- Run documentation maintenance and adversarial review only after native validation passes. Leave merge and publication for a later `publish` request. - -## Assumptions - -- Python 3.11+, Git, PowerShell 7, and Codex are already installed. -- Existing managed installation locations remain valid on Windows. -- The user’s native VM supplies Windows proof; no Windows CI is added. -- No applicable earlier Plan history record exists for CPK-039. - - - diff --git a/.agent/plan-history/plan-summary.20260822T050100617085Z.fd7dfe4c94e461a1824112794d31e1372d316ccf79eed8a3937d2754c1157e40.md b/.agent/plan-history/plan-summary.20260822T050100617085Z.fd7dfe4c94e461a1824112794d31e1372d316ccf79eed8a3937d2754c1157e40.md deleted file mode 100644 index 0520227..0000000 --- a/.agent/plan-history/plan-summary.20260822T050100617085Z.fd7dfe4c94e461a1824112794d31e1372d316ccf79eed8a3937d2754c1157e40.md +++ /dev/null @@ -1,99 +0,0 @@ - -# CPK-040 — Save Plans at Acceptance - -## Summary - -A prompt such as `Implement the plan.` must save the preceding Plan before implementation begins. - -Do not add semantic acceptance detection. Every next `UserPromptSubmit` saves the preceding completed Plan. Therefore, acceptance and revision prompts both preserve history. - -Release this bugfix as `0.19.1`. - -## Diagnostic First Action - -Before fetching, branching, editing, installing, or creating files: - -- Inspect this chat’s rollout at `/home/mbeutler/.codex/sessions/2026/08/13/rollout-2026-08-13T20-56-24-019ffdc5-27d6-7583-9a3b-7499d22ed915.jsonl`. -- Confirm the latest accepted Plan has: - - A completed `Plan` item. - - An assistant response containing the exact `` envelope. - - A matching `task_complete` with `last_agent_message: null`. - - A following acceptance turn. -- Confirm that no corresponding `.agent/plan-history` or specification-sibling record exists. -- Inspect the installed hook configuration and generated Codex hook schemas. -- Record the redacted event sequence and observed failure in the CPK-040 ExecPlan after creating the branch. -- Recover the exact accepted Plan from this rollout into repository and sibling history before other tracked edits. - -## Implementation - -- Create branch `cpk-040-plan-history-capture` from `ec07371a`. Do not implement on `main`. -- Keep the existing `Stop` capture for compatibility. -- Add one standard-library reverse transcript reader: - - Inspect only the newest completed turn. - - Use the raw assistant response as the saved content. - - Use the completed `Plan` item as the completion discriminator. - - Derive thread and turn identity from rollout fields. - - Stop immediately when the newest completed turn is not a Plan. - - Do not backfill older pre-fix Plans. -- Run transcript capture before: - - Every `UserPromptSubmit`, regardless of current permission mode. - - `SessionStart` for `resume`, `compact`, and `clear`. - - `SessionEnd`, using the event and `transcript_path` exposed by Codex 0.149. -- Always write repository Plans to `.agent/plan-history/`. -- Also write exact sibling copies for all valid specification markers. -- Preserve the existing non-Git global fallback. -- Preserve each hook’s output contract. Emit one valid response per hook. -- Update only the canonical `plan-history` rule owner and affected product documentation. -- Bump the committed version from `0.19.0` to `0.19.1`. - -## Automated Checks - -- Add a redacted fixture copied from this chat’s real Plan and acceptance sequence. -- Add a focused acceptance check: - - Supply a transcript ending with a completed Plan. - - Invoke `UserPromptSubmit` with `Implement the plan.` - - Verify that the exact Plan exists before the hook returns. -- Check revision prompts, default permission mode, and Unicode exactness. -- Check `SessionStart`, `SessionEnd`, direct `Stop`, clear-session identity, retries, equal-content turns, and collision preservation. -- Check central discovery, valid siblings, explicit `none`, invalid markers, and hook-specific warning output. -- Check bounded reads with large prefixes, non-Plan suffixes, no-Plan transcripts, CRLF, and Windows paths. -- Update installer and doctor checks for `SessionEnd`. -- Add an opt-in live app-server test: - - Start a real Plan turn through `collaborationMode.mode = "plan"`. - - Read its raw response from the generated rollout. - - Start a default turn with `Implement the plan.` - - Verify that the installed hook saves the response before any agent tool action. - - Interrupt the acceptance turn and clean the temporary repository. -- Keep the live check outside the default suite because it requires authentication, network access, and model usage. - -## Delivery - -- Run focused checks, the full suite, shell checks, and rule-owner checks. -- Run scope-bound adversarial review. -- After review passes, run `python3 kit.py install --repo .` and `python3 kit.py doctor --repo .`. -- Run the live Plan acceptance check against the installed toolkit. -- Create one local checkpoint commit. Do not publish without a later request. -- Finalize roadmap state before the commit. Do not write progress state after it. - -## Prior Plan Reconciliation - -Record: `docs/plans/cpk-036-plan-history.md` -Status: superseded -Reason: Codex 0.149 completes Plan turns without the expected `Stop` hook. Specification-only records are also not globally discoverable. -Replacement: Save the newest completed Plan during the next `UserPromptSubmit`, including an implementation acceptance prompt. Also capture during supported session lifecycle events and retain `Stop` compatibility. - -## Assumptions - -- Acceptance is not detected from prompt wording. The lifecycle boundary is authoritative. -- Historical Plans missed before this repair are not bulk-imported. -- Crashes that bypass every lifecycle event remain outside the supported model. -- App-server Plan invocation is a test facility, not automatic mode switching in an active chat. -- No daemon, database, mutable cursor, dependency, or unrelated-session scan is added. - -Preflight: ready — this chat supplies the production event sequence and the acceptance-path regression fixture. - -Review: not started — planning only. -Docs: planned — correct the Plan capture and discovery contract. - - - \ No newline at end of file diff --git a/.agent/plan-history/plan-summary.20260822T065923051937Z.4415ee79c8b0327ba824768113192b4f60662d355fb4931876ec995a214a5526.md b/.agent/plan-history/plan-summary.20260822T065923051937Z.4415ee79c8b0327ba824768113192b4f60662d355fb4931876ec995a214a5526.md deleted file mode 100644 index 9848d7c..0000000 --- a/.agent/plan-history/plan-summary.20260822T065923051937Z.4415ee79c8b0327ba824768113192b4f60662d355fb4931876ec995a214a5526.md +++ /dev/null @@ -1,72 +0,0 @@ - -# CPK-041 — Explain Code Consequences Before Decisions - -## Summary - -Material code decisions must explain their visible result and implementation shape before asking the user to choose. - -Simple English will control the wording. The decision-handoff rule will control the required facts. - -Release this feature as version `0.20.0`. - -## Implementation Changes - -- Create branch `cpk-041-implementation-aware-decisions` from the reviewed CPK-040 commit. -- Keep `decision-handoffs.md` as the single rule owner. Add no new skill. -- Route Design Preflight questions through this owner. -- Require the `simple-english` skill before drafting the decision brief or choice widget. -- Keep the existing decision labels and material-choice boundary. - -For each option, require these facts: - -- `What you get`: Explain the visible behavior in plain language. -- `Code change`: State whether the option reuses, extends, replaces, or adds an owner. -- `Source`: Name the plain code role, followed by its file or symbol. -- `New moving parts`: Name new state, callbacks, workers, storage, queues, or state machines. State when none are added. -- `Tests and maintenance`: State the new proof cases, compatibility effects, and ongoing lifecycle obligations. - -Do not estimate line counts. Classify the change as local, multi-owner, or a new subsystem. - -Investigate each option before asking. If source does not prove an impact, label it `unknown` and explain the missing evidence. - -Show the complete brief before `request_user_input`. The widget only collects the choice and never serves as the sole explanation. - -After selection, record the chosen behavior and implementation shape in the active ExecPlan. - -## Interfaces and Records - -- The installed decision-handoff contract gains source-backed implementation consequences. -- No CLI, runtime API, dependency, or persistent product state changes. -- Create the CPK-041 ExecPlan and make CPK-041 the only Active roadmap task. -- Keep CPK-008’s trigger, fixed labels, and exclusions. Extend its incomplete definition of an option’s “effect.” -- Keep CPK-040 Plan capture unchanged. - -## Test Plan - -- Prove that Design Preflight routes material questions to the decision-handoff owner. -- Prove that the owner invokes Simple English for the brief and widget. -- Prove that each option includes visible behavior, code shape, source, moving parts, and maintenance effects. -- Prove that the widget cannot replace the complete brief. -- Prove that routine questions and discoverable facts remain concise. -- Prove that unsupported code-impact claims use `unknown`. -- Prove that the rule requires no line estimate or new skill. -- Run the full toolkit suite, rule-owner checks, link checks, manifest checks, and diff checks. -- Run scope-bound adversarial review. -- Install the reviewed toolkit and run Doctor. -- Use a clean Codex planning session to repeat the supplied paging decision. Confirm that the new brief is understandable before the choice widget appears. -- Create one local checkpoint commit. Do not publish without a later request. - -## Assumptions - -- “Code shape only” means structural impact without line estimates. -- Source anchors use a plain role first and a file or symbol second. -- Material technical choices receive the full brief. Minor preferences do not. -- CPK-041 uses a branch because it has one implementation stream and no parallel writers. - -## Prior Plan Reconciliation - -- CPK-008 is carried. Its material-choice trigger, labels, and exclusions remain authoritative. -- CPK-040 is carried. Its Plan capture and delivery constraints remain unchanged. - - - \ No newline at end of file diff --git a/.agent/plan-history/plan-summary.20260823T052048899607Z.c539b46a7e5fa56092a382fef046fd00d4271c42c4fda8e0f0e2216ce94df122.md b/.agent/plan-history/plan-summary.20260823T052048899607Z.c539b46a7e5fa56092a382fef046fd00d4271c42c4fda8e0f0e2216ce94df122.md deleted file mode 100644 index aaa3ed3..0000000 --- a/.agent/plan-history/plan-summary.20260823T052048899607Z.c539b46a7e5fa56092a382fef046fd00d4271c42c4fda8e0f0e2216ce94df122.md +++ /dev/null @@ -1,117 +0,0 @@ - -# CPK-042 — Split Large Plans into Reviewed Checkpoints - -## Summary - -Plan Mode will divide large work by semantic boundaries, not arbitrary point counts. - -One ExecPlan will contain stable, ordered subtasks. Each subtask must produce one independently verifiable outcome. - -Each subtask will receive focused validation and adversarial review before its checkpoint commit. One final coherence review will check the complete feature. - -Release this feature as version `0.21.0`. This design follows OpenAI’s guidance for independent milestones and frequent commits. [Official OpenAI ExecPlan guidance](https://developers.openai.com/cookbook/articles/codex_exec_plans/) - -## Implementation Changes - -### Checkpoint 1: Add reviewed-subtask delivery - -Extend Adversarial Review with a `checkpoint` mode. - -- Compare the staged subtask with the previous accepted checkpoint. -- Review the new subtask, its direct dependencies, and its interaction with completed checkpoints. -- Do not reopen unchanged checkpoint code. -- Use existing delta reviews for corrections to the current checkpoint. -- Keep production-defect accounting active across the complete task. -- Delay review closure and roadmap completion until final coherence passes. - -Update Delivery Lifecycle to permit a local checkpoint commit only after that subtask has a final clean review result. - -Keep the task Active after intermediate commits. Do not authorize a push, merge, tag, release, or publication. - -Run focused checks and full validation. Review this checkpoint with the existing full-review workflow, then create its local checkpoint commit. - -### Checkpoint 2: Add semantic plan splitting and replanning - -Extend the ExecPlan owner in `.agent/PLANS.md`. - -Require multiple subtasks when work contains separately verifiable: - -- User-visible outcomes. -- Primary code owners. -- Foundation and consumer stages. -- Migrations and later adoption. -- Interfaces that can remain valid before later work starts. - -Do not use a numeric action limit. Do not create artificial splits when one stateful sequence or atomic migration requires one proof boundary. - -Use one stable subtask identifier for each checkpoint. Do not renumber completed subtasks. - -Each subtask must state: - -- Its observable outcome. -- Its primary owner and allowed change boundary. -- Its dependencies on earlier subtasks. -- Its implementation result. -- Its exact validation command and required oracle. -- Its checkpoint review and local commit boundary. - -Extend Plan History for checkpoint replanning. - -- Read the current ExecPlan, applicable Plan records, and completed checkpoint history. -- Keep completed subtask outcomes and accepted contracts unchanged. -- Permit splits, merges, and reordering only for unfinished subtasks. -- Record scoped supersession when a new Plan replaces unfinished work. -- Add a corrective subtask when a new requirement changes completed behavior. -- Never amend or rewrite a completed checkpoint commit. - -Update version `0.20.0` to `0.21.0`, focused tests, task documentation, roadmap state, and checksums. - -Review this checkpoint against the first checkpoint commit. Then run one cumulative coherence review before review closure and the final local commit. - -## Interfaces and Ownership - -The review-result schema gains `checkpoint` as a review mode. Its packet gains the subtask identifier and previous accepted checkpoint. - -The ExecPlan remains the only durable implementation plan. No child ExecPlans, parent index, task database, action counter, dependency service, or new skill will exist. - -The Plan capture runtime remains unchanged. It already stores distinct accepted replans beside the same ExecPlan without overwriting earlier records. - -## Test Plan - -- Prove that semantic split triggers exist and no numeric ceiling exists. -- Prove that each subtask contains one outcome, dependencies, owner boundary, proof, review gate, and commit boundary. -- Prove that checkpoint review excludes unchanged completed checkpoints. -- Prove that final coherence covers all checkpoint interactions exactly once. -- Prove that review closure cannot occur after an intermediate checkpoint. -- Prove that two accepted Plans for one ExecPlan create distinct immutable history records. -- Prove that a replan preserves completed subtasks and changes only the unfinished tail. -- Prove that changing completed behavior creates a new corrective subtask. -- Run the complete Python suite, compilation, shell syntax, owner, route, manifest, and diff checks. -- Install the reviewed toolkit and require Doctor to report `Result: ready`. -- Run a clean Plan Mode smoke with several independent outcomes. Confirm that it produces one checkpointed ExecPlan. -- Run a second clean Plan Mode smoke after one simulated checkpoint. Confirm that replanning preserves the completed checkpoint. - -## Assumptions and Boundaries - -Use branch `cpk-042-large-plan-checkpoints` from synchronized commit `0013a3c`. - -Use one implementation stream. A worktree and multiple implementation agents are unnecessary. - -Checkpoint commits remain local until the user requests publication. - -The existing hook runtime, Git CLI, choice widget, roadmap format, and publication policy remain opaque and unchanged. - -## Prior Plan Reconciliation - -Record: `.agent/plan-history/plan-summary.20260822T050100617085Z.fd7dfe4c94e461a1824112794d31e1372d316ccf79eed8a3937d2754c1157e40.md` -Status: carried -Reason: CPK-040 already preserves multiple accepted Plan responses and links them to one ExecPlan. - -Record: `.agent/plan-history/plan-summary.20260822T065923051937Z.4415ee79c8b0327ba824768113192b4f60662d355fb4931876ec995a214a5526.md` -Status: carried -Reason: CPK-041 remains authoritative for source-backed material decisions and the choices made during this plan. - -Preflight: ready — reuse one ExecPlan, semantic subtask boundaries, reviewed checkpoint commits, and final coherence. - - - \ No newline at end of file diff --git a/.agent/plan-history/plan-summary.20260824T031427928859Z.f30d03e6b396d05f07f5ce7eebc8b8e8b81e2b1cfe8ebc739342a6e444ca6968.md b/.agent/plan-history/plan-summary.20260824T031427928859Z.f30d03e6b396d05f07f5ce7eebc8b8e8b81e2b1cfe8ebc739342a6e444ca6968.md deleted file mode 100644 index 43c4e0b..0000000 --- a/.agent/plan-history/plan-summary.20260824T031427928859Z.f30d03e6b396d05f07f5ce7eebc8b8e8b81e2b1cfe8ebc739342a6e444ca6968.md +++ /dev/null @@ -1,53 +0,0 @@ - - -# CPK-043 — Review PRs Before Hosted CI - -## Summary - -Correct PR publication so Codex reviews the latest commit while the PR remains draft. Hosted CI starts only after the review has no retained findings. - -OpenAI supports an explicit `@codex review` request on a PR. GitHub supports workflows that start when a PR becomes ready. Together, these remove the need for a new dispatcher or state machine. [OpenAI Codex review guidance](https://openai.com/index/introducing-upgrades-to-codex/), [GitHub workflow events](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows) - -Implement this bugfix as version `0.21.1`. Create `cpk-043-review-gated-publication` from the current CPK-042 branch. Do not modify either CPK-042 commit. - -## Publication Changes - -- Before any push, prove that task-branch pushes and draft PRs cannot start hosted CI. If `main` requires PRs but CI is not draft-safe, stop with a configuration error. Do not fall back to direct integration. -- Push the branch, open a draft PR, verify its scope, and post `@codex review`. -- Keep the PR draft while reviewing and correcting findings. Each push invalidates the earlier review. -- Define a clean review as a completed Codex review of the current head with no retained applicable findings. A raw thumbs-up is sufficient but not required when all comments are correctly excluded. -- Mark the PR ready only after the current-head review is clean. Readiness may then start hosted CI. -- If a later correction needs a push, convert the PR to draft first. Repeat the review gate before CI runs again. -- Preserve the existing latest-head CI, conversation-resolution, mergeability, squash-merge, and integration checks. - -Route every PR finding through the existing Adversarial Review owner: - -- Apply the scope and supported-model gates before accepting the reviewer’s severity. -- Resolve an excluded finding with boundary evidence. Do not change code, run preflight, count a defect, or stop publication. -- Send a contract gap for human scope direction without treating it as a severe defect. -- Send an applicable correction through the same Design Preflight, validation, documentation, and local review flow used for local findings. -- Stop immediately for a validated P0 or P1 in executable production code. Run the existing severe defect diagnostic and wait for human direction. -- Keep all detailed classification and severe-stop rules in `adversarial-review`. The publication owner only links to them. - -## Implementation and Checks - -- Update the canonical publication reference and its focused rule-owner test. Do not add a workflow, parser, publication script, or new runtime state. -- Add CPK-043 to the roadmap and create its ExecPlan. Carry CPK-042 forward unchanged. Freeze tracked task records before the task commit. -- Test these cases: - - A draft PR receives `@codex review` before readiness or CI. - - An irrelevant P1 is excluded before severity and does not stop. - - An applicable production-code P1 triggers the canonical severe stop. - - An applicable non-severe finding uses the local correction cycle. - - A fix push resets review and CI eligibility. - - CI that can run on a draft blocks publication before the remote branch is pushed. - - Only a clean current head can become ready and run required CI. -- Run the focused policy test, full test suite, syntax checks, checksum validation, and one clean-context review. -- Install the reviewed candidate into the live environment and require Doctor to report ready. -- Create one CPK-043 task commit. Leave publication for explicit authorization. - -## Assumptions - -- The spend gate uses the current Codex review, as selected. Human reviewers can use CI evidence later. -- Repositories that use PR mode configure hosted CI for ready PRs, not draft PRs or ordinary task-branch pushes. -- An automatic Codex review after readiness is not the required review gate. The explicit draft review already covered that exact commit. - \ No newline at end of file diff --git a/.agent/plan-history/plan-summary.20260824T135017227348Z.7cfbec79d5ce39f1a1d436a31dccfe0669c616f252b6793d4b90dc2b34ad13d6.md b/.agent/plan-history/plan-summary.20260824T135017227348Z.7cfbec79d5ce39f1a1d436a31dccfe0669c616f252b6793d4b90dc2b34ad13d6.md deleted file mode 100644 index 44350f0..0000000 --- a/.agent/plan-history/plan-summary.20260824T135017227348Z.7cfbec79d5ce39f1a1d436a31dccfe0669c616f252b6793d4b90dc2b34ad13d6.md +++ /dev/null @@ -1,122 +0,0 @@ - -# CPK-044 — Separate Review Findings from Correction Authority - -## Summary - -Release this feature as version `0.22.0`. - -Use Codex’s native review mode for local defect discovery. Then apply toolkit scope and correction gates before any edit. - -This addresses two proven differences: - -- The current local process uses a generic reviewer with preloaded scenarios and exclusions. -- Native Codex review independently examines the diff, repository, dependencies, and tests. This matches OpenAI’s documented PR-review approach. [OpenAI Codex review guidance](https://openai.com/index/introducing-upgrades-to-codex/) -- Recent [Tenant Keeper PR review](https://github.com/calculatetech/tenant-keeper/pull/1) and [Meridian PR review](https://github.com/calculatetech/meridian/pull/19) found defects after local review reported clean. - -The cloud PR model and internal prompt remain undocumented. Do not claim exact parity. - -## Review and Correction Changes - -### Native defect discovery - -Replace the generic review subagent with `codex review`. - -- Stage the complete candidate and require no unstaged tracked changes. -- Create an unreferenced Git commit from the staged tree. -- Use the applicable review parent: - - `full`: task base. - - `checkpoint`: previous accepted checkpoint. - - `delta`: previous reviewed candidate. - - `final`: task base. -- Put only the accepted intent and its source in the synthetic commit message. Do not preload exclusions, scenario conclusions, or correction directions. -- Run `codex review --commit `. -- If native review is unavailable or fails, stop. Do not fall back to the generic reviewer. -- After review, prove that the staged tree and tracked worktree did not change. - -Replace `coherence` mode with `final` mode. After correction deltas are clean, review the complete current candidate once. If that review finds a defect, use a delta correction and repeat `final`. The existing three-pass breaker remains the limit. - -### Source-independent finding gate - -Treat every local, PR, human, CI, audit, or user-supplied finding as an untrusted candidate. - -Apply these steps before severity or correction: - -1. Read the cited source and prove the execution path. -2. Classify the accepted end result: - - `wrong`: The finding can make an accepted result or documented current behavior incorrect. - - `unchanged`: The accepted result remains correct. Exclude and report the finding. - - `undefined`: No accepted result exists. Stop for human direction. -3. Apply the current scope and supported-model gates. -4. Validate severity only for a retained finding. -5. Apply the severe-stop breaker. -6. Classify correction authority. - -Permit automatic correction only when all these conditions are true: - -- The required result already exists. -- The existing code owner is clear. -- The correction only restores that result. -- The correction adds no feature, use case, scope, assumption, policy, owner, state, interface, dependency, fallback, or lifecycle. -- One direct regression check can prove the result. -- The correction qualifies for the Design Preflight small-change exception. - -Call this a `direct repair`. Incorrect math, comparisons, mappings, and branch order are representative examples. - -Classify every other correction as `decision required`. Complete the classification of all findings, make no partial fixes, render each decision separately, and halt. - -A reviewer’s suggested fix does not supply product authority. Explicit human direction can supply that authority. - -## Diagnostic and Records - -Change severe diagnostics to present each finding in this order: - -- `Problem`: Plain description of the fault. -- `End result`: `wrong`, `still correct`, or `unknown`, with one reason. -- `Prevention`: The smallest requirement, check, or review action that could have prevented the defect. -- `Required action`: The exact human decision. -- `Proof`: Compact requirement, execution path, escape reason, rule contribution, and source locations. -- `Portable summary`: A short self-contained correction record. - -Keep the complete evidence, automatic diagnostic trigger, separate finding blocks, and mandatory halt from CPK-021. Do not lead with the chronological reconstruction. - -Create two reviewed checkpoints: - -1. Native discovery, exact review targets, final-review mode, and correction authority. -2. Diagnostic presentation, documentation, version, and manifest updates. - -Create `docs/plans/cpk-044-review-correction-authority.md`. Make CPK-044 the only active roadmap item during implementation. Preserve the existing untracked environment files. - -## Test Plan - -Add focused contract checks for: - -- Every review source uses the same finding gate. -- Raw reviewer severity cannot authorize action. -- A proven wrong calculation receives a direct repair. -- A proposed feature, fallback, new state, new interface, or assumed requirement stops before edits. -- A mixed finding set with one direct repair and one decision-required correction makes no fixes. -- A technically valid observation with an unchanged end result is excluded, reported, and does not stop. -- An undefined result becomes a contract gap. -- A relevant P0 or P1 still runs the severe diagnostic and halts. -- Native review uses the exact staged tree and the correct parent for each mode. -- Native review failure has no generic fallback. -- `final` replaces `coherence` and reviews the complete candidate. -- Diagnostic summaries precede compact proof sections and keep findings separate. - -Run the complete toolkit suite, Python compilation, shell and PowerShell checks, rule-owner checks, link checks, manifest validation, and `git diff --check`. - -After review, install the candidate and require Doctor to report ready. Run one opt-in native-review smoke against a temporary synthetic commit. Confirm completion and an unchanged tracked tree. - -Create local checkpoint commits. Do not publish without a later request. - -## Assumptions and Prior Decisions - -- Carry CPK-040 and CPK-041 unchanged. -- Preserve CPK-042 checkpoint and delta reviews. Supersede only its limited coherence pass. -- Preserve CPK-043 PR sequencing. Its findings now use the new correction-authority gate. -- Preserve CPK-021’s automatic diagnostic and halt. Supersede only its chronology-first presentation. -- Preserve the existing scope and supported-model definitions. -- Add no review parser, daemon, service, dependency, telemetry, or model-evaluation harness. - - - \ No newline at end of file diff --git a/.agent/plan-history/plan-summary.20260824T164719361941Z.f1479c9effab9071b8ccaa86dce1dbee407b79647c6bb7d542aea8c75caae32b.md b/.agent/plan-history/plan-summary.20260824T164719361941Z.f1479c9effab9071b8ccaa86dce1dbee407b79647c6bb7d542aea8c75caae32b.md deleted file mode 100644 index 8a20cc8..0000000 --- a/.agent/plan-history/plan-summary.20260824T164719361941Z.f1479c9effab9071b8ccaa86dce1dbee407b79647c6bb7d542aea8c75caae32b.md +++ /dev/null @@ -1,128 +0,0 @@ - -# CPK-045 — Close Every Behavioral Boundary - -## Summary - -The existing design rule is correct, but its enforcement is incomplete. - -Scenario Proof has no denominator that proves every explicit boundary was considered. It also lacks a post-implementation conformance gate. - -Release the correction as version `0.23.0`. Create `cpk-045-boundary-trace-closure` from commit `388b23f`. - -## Research Decision - -NeuroArxiv searched `cs.SE`, `cs.AI`, and `cs.PL`. It read 12 abstracts across four approaches: - -- Traceability: [T-SimCSE](https://arxiv.org/abs/2603.11800) `[rel7 prac7 rig8]`, [legal traceability](https://arxiv.org/abs/2502.04916) `[rel5 prac7 rig8]`, [TraceLLM](https://arxiv.org/abs/2602.01253) `[rel8 prac6 rig8]`. -- Evidence gates: [PROBE](https://arxiv.org/abs/2605.08717) `[rel8 prac8 rig8]`, [context compression](https://arxiv.org/abs/2605.11051) `[rel7 prac5 rig6]`, [embodied agents](https://arxiv.org/abs/2510.21902) `[rel3 prac5 rig6]`. -- Executable properties: [metamorphic adequacy](https://arxiv.org/abs/2412.20692) `[rel8 prac7 rig8]`, [substructural PBT](https://arxiv.org/abs/2108.01610) `[rel6 prac3 rig6]`, [ConCert](https://arxiv.org/abs/2208.00758) `[rel7 prac3 rig7]`, [programmable PBT](https://arxiv.org/abs/2602.18545) `[rel8 prac4 rig6]`, [αCheck](https://arxiv.org/abs/1604.08345) `[rel5 prac3 rig7]`. -- Intent-driven regression: [Cleverest](https://arxiv.org/abs/2501.11086) `[rel8 prac7 rig9]`. - -The selected path is an external boundary trace with an evidence gate. Planning writes it. Implementation and tests must close it. - -Avoid semantic-similarity ranking, a formal property language, mutation tooling, and post-failure recovery machinery. These approaches add cost without proving source completeness. - -OpenAI’s [ExecPlan guidance](https://developers.openai.com/cookbook/articles/codex_exec_plans/) requires self-contained plans and observable validation. It does not provide a boundary-trace gate. The toolkit must own this mechanism. - -## Implementation Changes - -### CP1 — Create the complete boundary inventory - -Extend the existing Scenario Discrimination owner. Do not add a skill or another durable plan. - -Before implementation: - -- Enumerate every in-scope requirement that limits, selects, excludes, relates, or preserves an outcome. -- Give each boundary a stable `B#` identifier. -- Record its source, condition or invariant, both sides, required oracles, applicable entry points, and Scenario Proof rows. -- Classify every relevant source clause as mapped, non-boundary, opaque, deferred, or contract gap. -- Inspect the complete source set. Do not stop after duplicate-looking clauses. -- Require one scenario per distinct production path unless one composed scenario proves all paths. -- Permit invariant boundaries whose correct results are equal. Their contrast must expose the nearest wrong behavior. -- Make any new or changed behavioral boundary override the small-change exception. Direct bugs with no boundary change retain the exception. - -Add the boundary inventory to the existing preflight card and Phase 1 result. Merge the accepted inventory into the task ExecPlan. - -### CP2 — Add trace closure before native review - -After implementation and final documentation, run one fresh read-only trace-closure verifier. - -Give it the raw requirement sources, accepted inventory, Scenario Proof, current diff, production source, and tests. It must independently enumerate the source boundaries before it checks existing `B#` records. - -Add this result shape to the existing preflight review interface: - -```json -{ - "reviewer": "boundary-trace-closure", - "source_inventory_complete": true, - "missing_or_unsupported": [], - "boundaries": [ - { - "boundary_id": "B1", - "path_id": "P1", - "entry_point": "path:line", - "gates": ["path:line"], - "enforcement_point": "path:line", - "terminal_owner": "path:line", - "implementation_matches": true, - "fixture_matches_discriminator": true, - "nearest_wrong_meaning_would_fail": true, - "both_sides_executed": true, - "terminal_oracle_reached": true, - "check": "exact command", - "result": "pass" - } - ], - "decision": "pass" -} -``` - -Any `false`, `unknown`, missing boundary, unsupported classification, or missing path blocks native review. - -The verifier must inspect the test body. A positive-only check, component check, aggregate suite result, or writer report cannot close a boundary. - -Run trace closure immediately before native review. Invalidate it after changes to requirements, boundary records, production paths, or named tests. - -Keep native `codex review` independent. Do not send it the trace record. - -## Test Plan - -Add focused contract tests that prove: - -- Every authoritative clause receives a disposition. -- A later distinct boundary cannot hide behind duplicate-looking clauses. -- Mapped and unmapped inputs produce the required subscription-staging outcomes. -- Equal-result invariants remain valid boundaries. -- Every applicable production entry point receives proof. -- A positive-only test blocks review. -- A fixture that changes the discriminator and an unrelated gate blocks review. -- A broader helper fails `nearest_wrong_meaning_would_fail`. -- A traced documentation or implementation change invalidates closure. -- A direct arithmetic bug with no boundary change retains the small-change exception. - -Run one clean-context forward test with the supplied broader-helper defect. Phase 1 must derive both mapped and unmapped cases. Trace closure must reject the broader implementation and positive-only test. - -Run all toolkit tests, skill validation, Python and shell checks, PowerShell parsing, rule-owner checks, link checks, manifest validation, and `git diff --check`. - -Use reviewed checkpoints for CP1 and CP2. Then run one final complete-candidate native review. Install the reviewed candidate and require Doctor to report `Result: ready`. - -## Assumptions and Defaults - -- This mechanism reduces semantic omissions. It does not claim formal completeness. -- The fresh closure verifier is the semantic gate. No parser or coverage percentage is added. -- Documentation is final before trace closure. -- Review Closure updates do not invalidate trace closure unless they change a traced source. -- CPK-045 becomes the only Active roadmap task during implementation. -- Local commits do not authorize publication. - -## Prior Plan Reconciliation - -- CPK-040 is carried. Plan capture remains unchanged. -- CPK-041 is carried. Material decisions still require source-backed effects. -- CPK-042 is carried. CP1 and CP2 use reviewed checkpoints and one final review. -- CPK-043 is carried. Pull-request sequencing remains unchanged. -- CPK-044 is carried. Native review and correction authority remain unchanged. -- CPK-022, CPK-028, CPK-034, and CPK-035 remain authoritative. CPK-045 adds source completeness and post-implementation closure. - - - \ No newline at end of file diff --git a/.agent/plan-history/plan-summary.20260825T002758364682Z.4eba52594f2ef5bdbe93f4f0ead7b61802e894668d23c749b5af459f65a19437.md b/.agent/plan-history/plan-summary.20260825T002758364682Z.4eba52594f2ef5bdbe93f4f0ead7b61802e894668d23c749b5af459f65a19437.md deleted file mode 100644 index ef992e2..0000000 --- a/.agent/plan-history/plan-summary.20260825T002758364682Z.4eba52594f2ef5bdbe93f4f0ead7b61802e894668d23c749b5af459f65a19437.md +++ /dev/null @@ -1,61 +0,0 @@ - -# CPK-046 — RepoWise Worktree Recovery - -## Damage assessment - -- Preserve `8a0b82e`; it is valid repository-local work. Local `main`, `origin/main`, the live toolkit, and the shared Git hook all remain unchanged. -- No damaged work was committed or published. The rejected work is confined to `task/cpk-046-repowise-worktree-bootstrap` and its worktree. -- The staged candidate adds duplicate repository ownership logic, redirects linked worktrees to the primary checkout, introduces an undocumented Git 2.31 requirement, and leaves version `0.23.0` unchanged. Delete it rather than salvage it. -- The foreign session also created `/tmp/.git` and `/tmp/.codex`. `/tmp/.git` caused Plan History to mistake temporary directories for repositories; the assessment then generated `/tmp/.agent`. -- Unreachable review objects are harmless and can expire through normal Git maintenance. - -## Checkpoint 1 — Containment and authority - -- Record the incident evidence in ignored test-results storage. Then remove the rejected worktree, its branch, the three verified `/tmp` marker directories, and the named assessment temp repositories and logs. Report that the discarded staged work is not recoverable. -- Create `cpk-046-repowise-worktree-recovery` from `8a0b82e`. Do not modify tracked files on `main`. -- Add one canonical Delivery Lifecycle rule: failures in shared tooling, dependencies, live installations, or other repositories authorize read-only diagnosis only. Agents must obtain explicit user authority before modifying another repository. -- Change Repository Knowledge’s ambiguous “restore the code graph” instruction to route to that authority owner and stop with a portable diagnostic when in-scope recovery fails. -- Add a focused rule-owner test that blocks duplicate cross-repository authority rules. -- Add a Design Preflight exemption for strict simplifications: no independent challenger is required when the correction deletes or rejects the starting design, uses an existing upstream/native capability, and adds no interface, persistent state, or broader behavior. -- Review this checkpoint once and commit it separately. - -## Checkpoint 2 — Minimal RepoWise correction - -- Upgrade the owned RepoWise installation from `0.41.0` to `0.45.0` and bump the toolkit bugfix version from `0.23.0` to `0.23.1`. -- Permit an in-place forced upgrade only when the outdated executable is the exact toolkit-owned path recorded by the install manifest. Continue rejecting unowned or differently located installations. -- Pass the actual linked-worktree root to RepoWise. RepoWise 0.45 already creates a separate worktree index, seeds it from the base checkout, and leaves the base unchanged. Do not add the rejected primary-checkout resolver. [RepoWise worktree guidance](https://github.com/repowise-dev/repowise/blob/main/docs/scale/WORKTREES.md), [RepoWise changelog](https://github.com/repowise-dev/repowise/blob/main/docs/CHANGELOG.md) -- Make Doctor resolve the shared hook directory with `git rev-parse --git-path hooks`. Do not use `--path-format`. Git defines hooks as common worktree data and runs them from the active working tree. [Git hooks](https://git-scm.com/docs/githooks), [Git repository layout](https://git-scm.com/docs/gitrepository-layout) -- Reject `remove-repo` from a linked worktree before any mutation because uninstalling its shared hook would disable sibling worktrees. Keep ordinary-checkout removal unchanged. -- Preserve the existing watcher compatibility patch, keyless operation, empty-directory behavior, and Windows launcher repair. -- Update the dependency lock, license declaration to `AGPL-3.0-or-later`, documentation, roadmap, checksums, and manifest. Add no new command, configuration, state marker, wrapper hook, or LLM dependency. -- Review this checkpoint once, then run one final whole-candidate coherency review. - -## Validation and delivery - -- Prove owned `0.41.0` upgrades to `0.45.0`; matching installations are reused; unowned mismatches stop safely. -- Exercise setup, bootstrap, Doctor, watcher indexing, hook-driven commit updates, and MCP startup in real ordinary and linked worktrees. -- Confirm linked worktree changes update its index without modifying the base index. -- Confirm linked removal stops before changing configuration, indexes, or the shared hook. -- Retain tests for empty/non-Git directories, Windows launchers, Plan History repository detection, routing, and unique rule ownership. -- Run the complete test suite, compilation checks, shell and PowerShell checks, checksum validation, and the final native review. -- After clean review, update the live toolkit and repeat Doctor plus linked-worktree MCP smoke tests. Do not publish without a separate publication request. - -## Prior Plan reconciliation - -Carry forward these records without superseding them: - -- `.agent/plan-history/plan-summary.20260822T050100617085Z.fd7dfe4c94e461a1824112794d31e1372d316ccf79eed8a3937d2754c1157e40.md` -- `.agent/plan-history/plan-summary.20260822T065923051937Z.4415ee79c8b0327ba824768113192b4f60662d355fb4931876ec995a214a5526.md` -- `.agent/plan-history/plan-summary.20260823T052048899607Z.c539b46a7e5fa56092a382fef046fd00d4271c42c4fda8e0f0e2216ce94df122.md` -- `.agent/plan-history/plan-summary.20260824T031427928859Z.f30d03e6b396d05f07f5ce7eebc8b8e8b81e2b1cfe8ebc739342a6e444ca6968.md` -- `.agent/plan-history/plan-summary.20260824T135017227348Z.7cfbec79d5ce39f1a1d436a31dccfe0669c616f252b6793d4b90dc2b34ad13d6.md` -- `.agent/plan-history/plan-summary.20260824T164719361941Z.f1479c9effab9071b8ccaa86dce1dbee407b79647c6bb7d542aea8c75caae32b.md` - -Preflight: ready — the replacement is strictly simpler than the rejected candidate; the unnecessary independent challenge was canceled. - -Review: not started — planning only. - -Docs: planned — ExecPlan, roadmap, RepoWise behavior, dependency, and authority documentation. - - - \ No newline at end of file diff --git a/.agent/plan-history/plan-summary.20260825T002911279202Z.940432714b78524077326cf1dea7571142fa6038e878a2fb7e884024bc8775a8.md b/.agent/plan-history/plan-summary.20260825T002911279202Z.940432714b78524077326cf1dea7571142fa6038e878a2fb7e884024bc8775a8.md deleted file mode 100644 index da4c336..0000000 --- a/.agent/plan-history/plan-summary.20260825T002911279202Z.940432714b78524077326cf1dea7571142fa6038e878a2fb7e884024bc8775a8.md +++ /dev/null @@ -1,60 +0,0 @@ - -# CPK-046 — RepoWise Worktree Recovery - -## Damage assessment - -- Preserve `8a0b82e`; it is valid repository-local work. Local `main`, `origin/main`, the live toolkit, and the shared Git hook remain unchanged. -- No damaged work was committed or published. The rejected work is confined to `task/cpk-046-repowise-worktree-bootstrap` and its worktree. -- Delete the staged candidate rather than salvage its duplicate ownership logic, primary-checkout redirection, and undocumented Git requirement. -- Remove the verified `/tmp/.git`, `/tmp/.codex`, and `/tmp/.agent` debris. Leave unreachable review objects to normal Git maintenance. - -## Checkpoint 1 — Containment and authority - -- Record the incident evidence in ignored test-results storage. Then remove the rejected worktree, its branch, and the exact verified temporary paths. -- Create `cpk-046-repowise-worktree-recovery` from `8a0b82e`. Do not modify tracked files on `main`. -- Create the CPK-046 ExecPlan. Copy and link every applicable unlinked Plan History record beside it before implementation. -- Add one Delivery Lifecycle rule requiring explicit user authority before modifying another repository because shared tooling failed. -- Make Repository Knowledge route failures to that owner and stop with a portable diagnostic. -- Add a unique-owner test for the authority rule. -- Exempt strict simplifications from independent design challenges when they use existing upstream or native behavior and add no interface, state, or broader behavior. -- Run one checkpoint native review and commit the accepted checkpoint. - -## Checkpoint 2 — Minimal RepoWise correction - -- Upgrade the toolkit-owned RepoWise installation from `0.41.0` to `0.45.0`. Bump the toolkit bugfix version from `0.23.0` to `0.23.1`. -- Force an upgrade only for the exact toolkit-owned path recorded by the install manifest. Reject unowned mismatches. -- Pass the actual worktree root to RepoWise and rely on its native linked-worktree support. Do not add a primary-checkout resolver. [RepoWise worktrees](https://github.com/repowise-dev/repowise/blob/main/docs/scale/WORKTREES.md), [RepoWise changelog](https://github.com/repowise-dev/repowise/blob/main/docs/CHANGELOG.md) -- Resolve hooks with `git rev-parse --git-path hooks`. Do not use `--path-format`. [Git hooks](https://git-scm.com/docs/githooks) -- Reject `remove-repo` from linked worktrees before mutation because their hook is shared. Keep ordinary-checkout removal unchanged. -- Preserve the watcher patch, keyless operation, empty-directory behavior, and Windows launcher repair. -- Update the dependency lock, license declaration, documentation, roadmap, checksums, and manifest. Add no new command, state marker, wrapper hook, or LLM dependency. -- Run one checkpoint native review and commit the accepted checkpoint. -- Run one final native review of the complete staged candidate. Do not perform a separate coherency review. - -## Validation and delivery - -- Test owned upgrades, matching-version reuse, unowned conflicts, Windows launchers, and empty/non-Git directories. -- Exercise setup, bootstrap, Doctor, watcher indexing, hook-driven commits, and MCP startup in real ordinary and linked worktrees. -- Confirm each linked worktree has its own index and does not modify the base index. -- Confirm linked removal stops before changing configuration, indexes, or the shared hook. -- Run the complete test suite, compilation, shell and PowerShell checks, rule-owner checks, and checksum validation. -- After a clean final native review, update the live toolkit and repeat Doctor plus linked-worktree MCP smoke tests. -- Do not publish without a separate publication request. - -## Prior Plan reconciliation - -The six earlier Plan History records remain carried. - -Record: `.agent/plan-history/plan-summary.20260825T002758364682Z.4eba52594f2ef5bdbe93f4f0ead7b61802e894668d23c749b5af459f65a19437.md` -Status: superseded -Reason: The user clarified that coherency reviews have been replaced with native reviews. -Replacement: Use checkpoint native reviews followed by one final native review of the complete candidate. All other decisions remain carried. - -Preflight: ready — this correction is strictly simpler than the rejected candidate. - -Review: not started — planning only. - -Docs: planned — ExecPlan, roadmap, RepoWise behavior, dependency, and authority documentation. - - - \ No newline at end of file diff --git a/.agent/plan-history/plan-summary.20260825T172626414955Z.9eaf7888a286b18f69d5a94869ee99522214d23dd715a553664a2041108fced3.md b/.agent/plan-history/plan-summary.20260825T172626414955Z.9eaf7888a286b18f69d5a94869ee99522214d23dd715a553664a2041108fced3.md deleted file mode 100644 index 6ec5a5e..0000000 --- a/.agent/plan-history/plan-summary.20260825T172626414955Z.9eaf7888a286b18f69d5a94869ee99522214d23dd715a553664a2041108fced3.md +++ /dev/null @@ -1,89 +0,0 @@ - -# CPK-047 — Bound Preflight and Reconcile Publication - -## Summary - -Correct two process defects in version `0.23.2`. - -Limit preflight to evidence that can change the accepted outcome. Keep one challenger until it completes or reports an error. - -Require separate local and PR reviews. After a remote merge, fast-forward local `main` before publication ends. - -Official OpenAI documentation defines `codex review` as a local target review. It defines `@codex review` as a GitHub PR review. [Local review](https://learn.chatgpt.com/docs/developer-commands?surface=cli#codex-review), [PR review](https://learn.chatgpt.com/docs/third-party/github#request-a-codex-review) - -Create branch `cpk-047-bounded-preflight-publication` from synchronized `main`. Use two checkpoint commits because the fixes have separate owners. - -## CP1 — Bound Preflight - -- Build one source packet before the challenger starts. -- Include the accepted outcome, explicit requirements, relevant product specifications, direct composing owners, path gates, state writers, and direct checks. -- Interpret “complete source set” as complete within the accepted task boundary. -- Permit expansion for authoritative product evidence or a direct composing-owner relationship. -- Require each expansion to name its source, relevance basis, and evidence. -- Do not expand for reachability, opaque owners, deferred work, future use cases, or unrelated lifecycles. -- Add `source_scope` to the Phase 1 result. Include `initial_sources` and evidence-backed `expansions`. -- Keep one challenger identity for both phases and one coordinator comparison. -- Put generic task liveness in Coordination. Elapsed time cannot authorize a duplicate delegated task. -- Route an actual challenger error to the existing one-attempt Supported Model rule. Stop and report the error. -- Add no numeric timeout, retry, cancellation system, or durable challenger state. - -Review CP1 with checkpoint mode. Commit it after the focused checks and clean review. - -## CP2 — Preserve Publication State - -- Keep native local review and GitHub PR review as separate cumulative gates. -- Apply Review Closure, freeze tracked records, and create the local task commit before publication. -- Record the frozen local task head. Do not require its tree to equal the pre-closure review tree. -- After the push, require the remote task branch and PR head to equal the local task head. -- Request `@codex review` for that exact PR head. A clean local review cannot satisfy this gate. -- Apply existing local correction and review rules before each correction push. -- Reset PR review and CI eligibility after every push. - -After GitHub completes the squash merge: - -1. Record the GitHub merge commit. -2. Fetch `origin`. -3. Find the worktree that contains local `main`. -4. Require no staged or unstaged tracked changes in that worktree. -5. Run `git merge --ff-only origin/main` in that worktree. -6. If no worktree contains `main`, switch the clean publishing worktree to `main`. -7. Fast-forward `main` there. -8. Prove that local `main` equals `origin/main`. -9. Prove that this head contains the recorded merge commit and published result. -10. Monitor required post-merge CI for the integrated head. - -Stop on dirty tracked state, checkout conflicts, divergence, or a failed fast-forward. Do not stash, reset, rebase, retry, or change untracked files. - -## Validation and Delivery - -- Extend the focused preflight test for bounded sources, evidence-backed expansion, one live challenger, and no automatic restart. -- Extend the publication test for cumulative review gates, exact task and PR heads, local-main fast-forward, and safe-stop behavior. -- Keep each new rule in one canonical owner. Add no duplicate review, failure, or Git-isolation rules. -- Use deterministic instruction checks. Do not add variable clean-context traces or executable-production trace closure. -- Run the focused checks, full suite, skill validators, link checks, shell checks, PowerShell checks, manifest validation, and `git diff --check`. -- Bump the committed source version from `0.23.1` to `0.23.2`. -- Review and commit CP2 as a checkpoint. -- Run one final native review from the task base. -- Apply Review Closure and create the final closure commit. -- Install the reviewed toolkit in the live environment. Require Doctor to report `Result: ready`. -- Do not publish without a later publication request. - -## Assumptions and Prior Plan Reconciliation - -- Use semantic scope instead of file, source, action, or time limits. -- Keep the CPK-035 two-phase challenger design. Clarify that its complete source set is task-boundary complete. -- Carry the CPK-042 checkpoint plan record unchanged. -- Carry the CPK-043 plan record. Clarify its current-head PR review and local integration requirements. -- Carry the CPK-044 plan record. Local native review and finding adjudication remain unchanged. -- Carry the final CPK-046 plan record. Use deterministic checks and one final native review. -- Direct publication, tags, releases, cleanup, non-GitHub providers, and destructive recovery remain unchanged. -- Use a normal branch because this task has one writable implementation stream. -- Do not add a skill, dependency, parser, publication script, daemon, database, or runtime state machine. - -Preflight: ready — use one evidence-bounded challenger and reconcile exact publication heads through local `main`. - -Review: not started — planning only. -Docs: planned — update the canonical rule owners, CPK-047 ExecPlan, roadmap, version, and checksums. - - - \ No newline at end of file diff --git a/.agent/plan-history/plan-summary.20260825T173129857080Z.a3ee26a1802fb85c5a0a100ccb3c33c1a6fff358bd20b65636adc61f8d0de377.md b/.agent/plan-history/plan-summary.20260825T173129857080Z.a3ee26a1802fb85c5a0a100ccb3c33c1a6fff358bd20b65636adc61f8d0de377.md deleted file mode 100644 index 7fee62c..0000000 --- a/.agent/plan-history/plan-summary.20260825T173129857080Z.a3ee26a1802fb85c5a0a100ccb3c33c1a6fff358bd20b65636adc61f8d0de377.md +++ /dev/null @@ -1,124 +0,0 @@ - -# CPK-047 — Repair Worktree Handoffs, Preflight, and Publication - -## Summary - -Correct three related process defects in version `0.23.2`. - -First, relocate pending Plan History records from the source worktree to the task worktree. Do not leave duplicate untracked files in local `main`. - -Then bound preflight and reconcile publication state. - -Official documentation defines `codex review` as local review. It defines `@codex review` as GitHub PR review. [Local review](https://learn.chatgpt.com/docs/developer-commands?surface=cli#codex-review), [PR review](https://learn.chatgpt.com/docs/third-party/github#request-a-codex-review) - -Create branch `cpk-047-bounded-preflight-publication` from synchronized `main`. Use three checkpoint commits. - -## CP1 — Transfer Pending Plan History - -Update the canonical Plan History owner. - -- Before work starts in another worktree, enumerate every worktree in the same Git repository. -- Find every applicable untracked central record and specification-sibling record. -- Copy each record to the same relative path in the task worktree. -- Compare the source and destination bytes. -- If the bytes match, remove the redundant untracked source copy. -- If the bytes differ, retain both records and stop. -- If the destination copy fails, retain the source and stop. -- Never remove a tracked record, collision record, unrelated record, or unique record. -- Keep central and specification-sibling records together in the task worktree. They have different purposes and are not redundant. -- Preserve record contents, event identity, timestamps, and filenames. -- Define this operation as relocation. It does not remove Plan history because the verified destination remains. -- Make the sequence repeatable. A partial copy can leave a harmless duplicate for the next attempt. -- Do not change the Plan capture hook. It cannot know which future worktree will implement the Plan. -- Do not add a helper, database, manifest, or new runtime state. - -Add a focused owner test for discovery, copy, byte comparison, safe removal, collision retention, and tracked-file protection. - -Review and commit CP1 before the other checkpoints. - -## CP2 — Bound Preflight - -- Build one source packet before the challenger starts. -- Include the accepted outcome, explicit requirements, product specifications, composing owners, path gates, state writers, and direct checks. -- Interpret “complete source set” as complete within the accepted task boundary. -- Permit expansion for authoritative product evidence or a direct composing-owner relationship. -- Require each expansion to name its source, relevance basis, and evidence. -- Do not expand for reachability, opaque owners, deferred work, future use cases, or unrelated lifecycles. -- Add `source_scope` to the Phase 1 result. Include `initial_sources` and evidence-backed `expansions`. -- Keep one challenger identity for both phases and one coordinator comparison. -- Put generic task liveness in Coordination. Elapsed time cannot authorize a duplicate delegated task. -- Route an actual challenger error to the existing one-attempt Supported Model rule. -- Add no numeric timeout, automatic retry, cancellation system, or durable challenger state. - -Review and commit CP2 as a checkpoint. - -## CP3 — Reconcile Publication - -Before publication classifies worktree state, apply the Plan History handoff from CP1. - -- Do not classify verified Plan History duplicates as unrelated files. -- Preserve all other untracked files. -- Stop for an untracked file only when Git reports an actual overwrite conflict. -- Stop for staged or unstaged tracked changes before the local-main update. - -Keep local native review and GitHub PR review as separate cumulative gates. - -- Apply Review Closure and freeze tracked records before the task commit. -- Record the frozen local task head. -- Push the task branch. -- Require the remote task branch and PR head to equal the local task head. -- Request `@codex review` for that exact PR head. -- Do not use a clean local review to satisfy the GitHub review gate. -- Apply local correction and review rules before each correction push. -- Reset PR review and CI eligibility after each push. - -After GitHub completes the squash merge: - -1. Record the GitHub merge commit. -2. Fetch `origin`. -3. Find the worktree that contains local `main`. -4. Apply the Plan History handoff before the clean-state gate. -5. Require no staged or unstaged tracked changes. -6. Run `git merge --ff-only origin/main`. -7. If no worktree contains `main`, switch the clean publishing worktree to `main`. -8. Fast-forward `main` there. -9. Prove that local `main` equals `origin/main`. -10. Prove that the head contains the recorded merge commit and published result. -11. Monitor required post-merge CI for that head. - -Stop on tracked changes, divergence, checkout conflicts, actual untracked-path conflicts, or a failed fast-forward. Do not stash, reset, rebase, or remove unrelated files. - -## Validation and Delivery - -- Test Plan History relocation before any unexpected-file or clean-state decision. -- Test byte-identical relocation, different-content preservation, partial-copy recovery, and tracked-record protection. -- Test bounded preflight sources, evidence-backed expansion, one live challenger, and no automatic restart. -- Test cumulative review gates, exact task and PR heads, local-main fast-forward, and safe-stop behavior. -- Keep each rule in one canonical owner. -- Use deterministic instruction checks. Do not add variable clean-context traces. -- Run the focused checks, full suite, skill validators, link checks, platform checks, manifest validation, and `git diff --check`. -- Bump the committed source version from `0.23.1` to `0.23.2`. -- Run one final native review from the task base after all checkpoints. -- Apply Review Closure and create the final closure commit. -- Install the reviewed toolkit in the live environment. Require Doctor to report `Result: ready`. -- Do not publish without a later publication request. - -## Prior Plan Reconciliation - -Record: `.agent/plan-history/plan-summary.20260825T172626414955Z.9eaf7888a286b18f69d5a94869ee99522214d23dd715a553664a2041108fced3.md` -Status: superseded -Reason: The publication checkpoint did not first relocate pending Plan History records from the `main` worktree. -Replacement: Add CP1 relocation before preflight and publication. Apply that owner before publication classifies worktree state. -Scope: unfinished subtasks CP1 and CP2. - -Carry the CPK-035 two-phase challenger design, CPK-042 checkpoint process, CPK-043 PR gate, CPK-044 finding gate, and final CPK-046 review process. - -Use a branch because this task has one writable implementation stream. - -Preflight: ready — CP1 is a strict simplification of the existing copy and byte-comparison handoff. - -Review: not started — planning only. -Docs: planned — update Plan History, Coordination, Design Preflight, Publication, CPK-047, roadmap, version, tests, and checksums. - - - \ No newline at end of file diff --git a/.agent/plan-history/plan-summary.20260825T183857932150Z.47ec1ac118b8c6c23f961b4099708aacc7031581a744bc389e6795e1c2007796.md b/.agent/plan-history/plan-summary.20260825T183857932150Z.47ec1ac118b8c6c23f961b4099708aacc7031581a744bc389e6795e1c2007796.md deleted file mode 100644 index e98953a..0000000 --- a/.agent/plan-history/plan-summary.20260825T183857932150Z.47ec1ac118b8c6c23f961b4099708aacc7031581a744bc389e6795e1c2007796.md +++ /dev/null @@ -1,69 +0,0 @@ - -# CPK-048 — Reconcile Shared Agent and Plan Instructions - -## Summary - -The toolkit correctly updates global `AGENTS.md` and `PLANS.md`, but it never updates repository-owned copies. Twenty-five older project copies therefore override the current checkpoint rules. - -Keep one canonical Plan contract. Do not add a migrator, Doctor warning, new skill, or duplicate checkpoint rule. Document the precedence, remove obsolete copies from eligible projects, and preserve deliberate project-specific rules. - -Keep version `0.23.2` because it has not been published. - -## CP1 — Document the Shared Contract - -- Add CPK-048 to the current unpublished branch and roadmap. -- Update the README in Simple English: - - The installer-managed `AGENTS.md` and `PLANS.md` apply across repositories. - - Repository `AGENTS.md` and `.agent/PLANS.md` files take priority. - - The installer and `setup-repo` never update repository-owned instruction files. - - Do not copy the global Plan contract into projects. - - Remove generic local Plan copies to inherit future toolkit updates. - - Keep only deliberate, focused project overrides in the nearest applicable `AGENTS.md`. -- Leave the canonical checkpoint rules in `.agent/PLANS.md`. -- Make no installer, runtime, skill, public-interface, or version change. -- Validate the documentation and run one native checkpoint review before the local toolkit commit. - -## CP2 — One-Time `~/Projects` Audit - -- Inventory instruction files again immediately before editing. Fetch each distinct Git remote once. -- For remote-backed repositories, require the working branch to contain the current upstream head. Fast-forward only clean, non-divergent branches. Do not stash, reset, rebase, or overwrite unrelated work. -- Exclude the toolkit’s canonical `.agent/PLANS.md`. -- Ignore these dirty historical Meridian worktrees entirely: - - `meridian-task-063e` - - `meridian-task-063e-rebuild` - - `meridian-task-063f` - - `meridian-task-063f-rebuild` - - `meridian-task-084a2` -- Audit Meridian `main` and the three clean task worktrees separately. Fetch the shared remote only once. - -For each eligible project: - -- Archive every untracked or non-Git Plan copy, with its original path and SHA-256 hash, under `~/.local/share/codex-practical-kit/audits/cpk-048/`. -- Remove obsolete `.agent/PLANS.md` copies. Tracked copies remain recoverable from Git; archived copies remain recoverable from the audit directory. -- Preserve Meridian’s production-complete checkpoint requirement in its root `AGENTS.md` before removing its customized Plan copy. -- Remove stale generic planning, review, progress, coordination, and publication rules from project `AGENTS.md` files. -- Preserve project-specific product, security, compatibility, build, versioning, release-evidence, and human-approval rules at their existing scope. -- Remove every reference to a deleted local Plan file. Do not copy toolkit lifecycle or checkpoint rules into another local owner. -- Create a documentation branch in each independent repository. Use existing clean Meridian task branches. -- Stage only `AGENTS.md` and `.agent/PLANS.md`, run one native instruction/configuration review, and create one local commit. Do not push or increment project versions. -- Stop only the affected repository if it has divergence, unexpected tracked changes, newer conflicting remote instructions, or an uncertain project-specific rule. Continue the read-only audit of other repositories and report the blocked repository. - -## Validation and Publication - -- Confirm the initial inventory: 25 stale Plan copies outside the toolkit. -- Expect 20 eligible copies to be removed. The five excluded dirty Meridian worktrees remain unchanged and must be reported. -- Confirm eligible repositories contain no stale `.agent/PLANS.md` routes or copied toolkit lifecycle rules. -- Confirm every Git commit changes only approved instruction paths and contains its refreshed upstream where applicable. -- Confirm no external repository was pushed. -- Run the complete toolkit checks and one final native review of the full toolkit candidate. -- Apply review closure, install the reviewed toolkit into the live environment, and require Doctor to report `Result: ready`. -- Resume publication of toolkit version `0.23.2` through the existing CPK-047 publication gates. External audit commits remain local. - -## Prior Plan Reconciliation - -- CPK-042 is carried. Semantic checkpoint guidance remains single-owned by the canonical Plan contract. -- The final CPK-047 Plan is carried. Its completed checkpoints and publication rules remain unchanged. -- CPK-048 is a new corrective task on the existing unpublished branch. It does not rewrite earlier checkpoint commits. - - - \ No newline at end of file diff --git a/.agent/plan-history/plan-summary.20260901T024803899174Z.f5becdd56d889aba50bf375a29ab0feb9012128e404e73e7a664e0243eb5ab8f.md b/.agent/plan-history/plan-summary.20260901T024803899174Z.f5becdd56d889aba50bf375a29ab0feb9012128e404e73e7a664e0243eb5ab8f.md deleted file mode 100644 index e8f933a..0000000 --- a/.agent/plan-history/plan-summary.20260901T024803899174Z.f5becdd56d889aba50bf375a29ab0feb9012128e404e73e7a664e0243eb5ab8f.md +++ /dev/null @@ -1,55 +0,0 @@ - -# CPK-053 — Require Continuous Production-Path Proof - -## Summary - -The trace gap is structural: current closure records entry points, gates, owners, checks, and terminal results separately. A verifier can combine component evidence even though no test traverses the complete production path. - -Implement this bugfix on branch `fix/cpk-053-continuous-path-proof` from `ee3aa1464e4a`. Release version `0.23.7`. - -## Key Changes - -- Keep Owner Composition as the single owner of traversal rules: - - One named runnable check must invoke the real production entry point. - - Each proof case must causally traverse every in-scope production owner or hop and reach the terminal oracle. - - Separate component tests fail, as do disconnected component calls bundled inside one test. - - Deterministic callbacks and async continuations are valid when the check drives them. Concurrent ordering remains excluded unless a product requirement enables it. - - Fakes can replace only opaque external systems. Replacing an in-scope hop leaves the path unclosed. -- Make Scenario Discrimination bind every path fact in a closure row to that row’s exact named check. Link to Owner Composition without copying its traversal rules. -- Extend the trace result interface with: - - `production_hops`: the complete in-scope hop inventory. - - `one_check_traverses_complete_path`: must be `true`. - - `external_boundary_seams`: permitted external seams, or an empty list. - - `replaced_in_scope_hops`: must be empty. -- Fail closure and add an exact `missing_tests` obligation when continuity, hop coverage, or seam placement is false, missing, unknown, or unsupported. -- Add the stable CPK-053 ExecPlan and roadmap result. Update `KIT_VERSION` and its exact assertion to `0.23.7`, then regenerate `MANIFEST.sha256`. Add no skill, parser, instrumentation, dependency, or second rule owner. - -## Test Plan - -Update the existing focused tests and CPK-045 forward fixture to prove: - -- Separate component tests cannot collectively close a path. -- Disconnected component calls inside one test body also fail. -- One real-entry traversal through every production hop passes. -- An external-provider fake passes; an in-scope writer or loader fake fails. -- A deterministically driven callback or async continuation passes. -- Every production entry point receives proof during initial and correction preflight. -- Full, checkpoint, delta, final, and reuse-only closure enforce the same rule. -- Missing traversal proof appears in `missing_tests`. -- Static toolkit rules remain outside semantic trace closure. -- Fresh trace-executor and native-review independence remain unchanged. -- The unique-owner test rejects copied guard text. - -Run the focused unit tests, the clean-context forward fixture, `./run-tests.sh`, shell and PowerShell syntax checks, `git diff --check`, and `sha256sum --check MANIFEST.sha256`. - -## Delivery - -Use one reviewed checkpoint because this is one coherent correction. Run deterministic checks and native review; do not run semantic trace closure on this static rule change. After a clean final review, commit the candidate, install that exact commit into the live environment, and require Doctor to report version `0.23.7` and `Result: ready`. Do not push until publication is separately requested. - -## Assumptions - -- “End-to-end” means the real in-repository path, not live third-party infrastructure. -- A named check may be parameterized, but every proof case must traverse the complete causal path. -- Existing gate, enforcement, and terminal fields remain; `production_hops` supplies the previously missing complete inventory. -- This is a patch-level process defect correction, not a new feature. - \ No newline at end of file diff --git a/.agent/plan-history/plan-summary.20260906T145108959420Z.4ca59f1efb35d2fec6091bc88b5848bb2e50226576f0a493f9ec85ed1838c57b.md b/.agent/plan-history/plan-summary.20260906T145108959420Z.4ca59f1efb35d2fec6091bc88b5848bb2e50226576f0a493f9ec85ed1838c57b.md deleted file mode 100644 index 3f09b53..0000000 --- a/.agent/plan-history/plan-summary.20260906T145108959420Z.4ca59f1efb35d2fec6091bc88b5848bb2e50226576f0a493f9ec85ed1838c57b.md +++ /dev/null @@ -1,68 +0,0 @@ - -# CPK-055 — Install and preserve the official Ponytail plugin - -## Summary - -Replace the toolkit’s partial Ponytail installation with the official Codex plugin. Preserve all six skills, lifecycle hooks, mode controls, and persistent defaults. - -Codex invokes these capabilities through its skill interface, including `@ponytail-review`. The upstream documentation does not promise a `/ponytail` slash-menu entry. [Ponytail documentation](https://github.com/DietrichGebert/ponytail#commands) - -The plugin and user selections will control Ponytail modes. The toolkit will stop changing them during planning, implementation, or review. - -## Implementation - -**CP1 — Remove toolkit mode overrides** - -- Remove the Ponytail implementation route from the managed AGENTS block. -- Remove automatic normal/full selections from the lifecycle instructions. Retain the existing test-scope and challenger-reasoning requirements. -- Remove the `normal mode` output from the managed prompt hook. Preserve Plan capture, its planning reminder, and other hook behavior. -- Update the corresponding instruction and installed-hook tests, then review and commit this checkpoint. - -**CP2 — Use native plugin installation** - -- Extend `kit.py` to inspect and install Ponytail through native Codex plugin commands: - - `codex plugin marketplace add DietrichGebert/ponytail` - - `codex plugin add ponytail@ponytail` -- Install only when absent. Preserve an existing official plugin’s version, settings, and enabled or disabled state. -- Honor the selected Codex home for inspection, installation, and diagnostics. -- Check Node.js and native plugin-command support before changing an existing installation. Report missing prerequisites directly. -- Treat a conflicting marketplace source or unowned standalone Ponytail skill as an installation conflict. -- Retire the old copied skill only when the previous toolkit manifest owns it and native installation succeeds. -- Update Doctor to check the native plugin and Node.js. Report a user-disabled plugin without re-enabling it. -- Remove Ponytail from the copied-skill dependency list. Keep plugin updates and removal under Codex’s plugin manager. -- Update installation documentation, third-party declarations, and checksums. Review and commit this checkpoint. - -## Full-removal documentation - -Document what normal uninstall and `--purge` remove, plus the additional steps for complete removal: - -1. Remove repository integrations and generated views before removing the toolkit. -2. Purge toolkit-owned files. -3. Perform optional Ponytail state cleanup before deleting its plugin cache. -4. Remove the plugin with `codex plugin remove ponytail@ponytail`, then remove its marketplace. -5. Remove RepoWise with `uv tool uninstall repowise`. Document optional `uv` cleanup when other tools no longer need it. -6. Identify retained Plan history, project indexes, and shared settings, with explicit cleanup choices. - -Include POSIX and Windows instructions. Account for Codex’s Ponytail data directory: the upstream cleanup script does not remove that state. - -## Validation - -- Prove fresh installation exposes all six skills and the declared hooks through a real isolated Codex installation. -- Exercise install → reinstall → uninstall and purge. Native plugin resources and user settings must remain intact. -- Contrast owned and unowned legacy skills, official and conflicting marketplaces, and selected versus default Codex homes. -- Test missing Node.js and missing plugin-command support separately. Both must preserve the previous installation before reporting failure. -- Exercise installed hooks with Plan and ordinary prompts. Confirm preserved history behavior and no toolkit mode directives. -- Check documented mode switching, off, status, persistent defaults, and lifecycle behavior using isolated plugin state. -- Run the full toolkit suite, required trace verification, checkpoint reviews, and final native review. Then update the host and run Doctor. - -## Decisions and reconciliation - -Use one CPK-055 ExecPlan and two reviewed checkpoints. No custom command aliases, Ponytail fork, mode storage, or automatic hook trust will be added. - -The user’s plugin-only mode choice supersedes the mode-selection requirements in CPK-028 and CPK-029. Preserve their historical records and unrelated requirements. - -Native Ponytail installations remain after toolkit uninstall, as selected. Publication remains a separate step. - - - - \ No newline at end of file diff --git a/.agent/plan-history/plan-summary.20260906T161604059175Z.811836c214ecc89cb39c692f4366e4e79e56a698bf0d01445feb86fcd2c725f4.md b/.agent/plan-history/plan-summary.20260906T161604059175Z.811836c214ecc89cb39c692f4366e4e79e56a698bf0d01445feb86fcd2c725f4.md deleted file mode 100644 index ea6e44f..0000000 --- a/.agent/plan-history/plan-summary.20260906T161604059175Z.811836c214ecc89cb39c692f4366e4e79e56a698bf0d01445feb86fcd2c725f4.md +++ /dev/null @@ -1,37 +0,0 @@ - -# CPK-056 — Ask material questions in dependency order - -## Summary - -Extend the existing interview rules so Codex settles prerequisite decisions before asking dependent questions. Keep interviews bounded by the requested outcome. - -Checkpoint relay is deferred. No diagnosis or correction-gate changes are included. - -## Implementation - -Keep [decision-handoffs.md](/home/mbeutler/Projects/codex-practical-kit/assets/skills/delivery-lifecycle/references/decision-handoffs.md) as the sole rule owner. - -- When product intent is unclear, identify material decisions and their prerequisites in working context. -- Resolve discoverable facts before asking the user. -- Ask the highest-impact question whose prerequisites are settled. Batch up to three independent questions when useful. -- After an answer or relevant discovery, reassess which questions remain necessary. Accept partial answers without repeating settled questions. -- Stop interviewing once material behavior, scope, and acceptance criteria are settled. Do not require exhaustive questioning or another confirmation of already approved decisions. -- Preserve the existing decision brief for each material technical choice. Adjust the single-question wording to permit bounded batches. - -Add no skill, dependency, hook, persistent decision tree, or duplicate planning artifact. Record CPK-056 through the existing roadmap lifecycle. - -## Validation and delivery - -Extend the existing decision-handoff test to cover prerequisite ordering, independent batches, partial answers, and the stopping condition. Retain its checks for source-backed options, brief ordering, and routine-question exclusions. - -Run the focused test, `./run-tests.sh`, rule-owner and link checks, manifest validation, and `git diff --check`. Finalize affected documentation before native review. After clean review, complete normal local delivery, installation, and Doctor checks. Publication remains separate. - -## Prior plan reconciliation - -Carry the CPK-041 Plan record forward: material-choice criteria, explanation requirements, and routine-question exclusions remain unchanged. Preserve the completed CPK-008 and CPK-041 specifications as historical records. - -Existing correction-authority and preflight requirements remain in force. Investigating a specific boundary escape remains separate from this interview improvement. - - - - \ No newline at end of file diff --git a/.agent/plan-history/plan-summary.20260906T184718818166Z.101806a6188b911af737dd47187082418727ed7042831dd332d77360d1cb6b93.md b/.agent/plan-history/plan-summary.20260906T184718818166Z.101806a6188b911af737dd47187082418727ed7042831dd332d77360d1cb6b93.md deleted file mode 100644 index 7c2607a..0000000 --- a/.agent/plan-history/plan-summary.20260906T184718818166Z.101806a6188b911af737dd47187082418727ed7042831dd332d77360d1cb6b93.md +++ /dev/null @@ -1,123 +0,0 @@ - -# CPK-056 — Improve interviews and assess rule adherence - -## Summary - -Combine the approved interview improvement with focused correction and proof clarifications. - -Use small tasks run by fresh agents to compare the current and revised rules. Grade their questions, decisions, and permitted edits against expectations withheld from those agents. - -Use one ExecPlan: `docs/plans/cpk-056-interviews-and-assessment.md`. Create a task branch from reviewed commit `24722f5`, preserving CPK-055. Relay remains deferred. Meridian remains untouched. - -## Implementation checkpoints - -### CP1 — Establish independent assessments and the baseline - -- Remove answer leakage from the existing CPK-045 forward fixture: explicit verdict lists, grading instructions, and answer-shaped response fields. -- Preserve every existing obligation, including the unnumbered source-inventory, initial-versus-correction, and equal-result cases. Assign neutral case identifiers. -- Keep agent inputs and coordinator-only grading criteria separate. Use neutral response fields: case identifier, verdict, evidence, and proposed action. -- Add a small case catalog under `tests/fixtures/`, containing disposable source examples, setup instructions, scripted interview replies, and separate grading criteria. -- Extend deterministic tests to verify complete case-to-grader correspondence and separation of inputs from expected answers. -- Freeze the cases and current rule snapshot. Run and retain baseline results before editing the live rule owners. - -This checkpoint adds no runner, framework, service, or dependency. - -### CP2 — Improve the interview - -Keep `decision-handoffs.md` as the sole interview rule owner. - -- Investigate discoverable facts before asking questions. -- Identify material decisions and their prerequisites in working context. -- Ask the highest-impact question whose prerequisites are settled. Permit batches of up to three independent questions. -- Reassess after partial answers or relevant discoveries. Remove obsolete questions and do not repeat settled ones. -- Stop when material behavior, scope, and acceptance criteria are settled. -- Preserve the complete, source-backed brief before a material technical choice. Explain unfamiliar purposes and terms before presenting implementation options. -- Keep routine questions concise. Add no persistent decision tree or additional approval step. - -Extend the existing interview contract test and run the scripted interview assessment against this checkpoint. - -### CP3 — Clarify correction entry and required proof - -**Correction entry** - -- Make failed local tests and builds explicit inputs to the existing correction-authority gate before a proposed corrective edit. -- Route Delivery Lifecycle to that owner without duplicating its conditions or triggering native review merely to classify a failure. -- Add `local-check` to the finding record’s source values. -- Preserve all existing direct-repair conditions, mixed-finding handling, and review sequencing. -- Preserve authorization for planned red-to-green implementation. An expected failing test does not require renewed approval for changes already covered by the accepted plan and preflight. - -**Simplification** - -- Clarify that strict simplification exempts only the challenger. -- It grants no correction authority and waives no applicable preflight record, boundary inventory, proof, documentation, or review requirement. - -**Proof** - -- Extend Owner Composition with an explicit decision-ownership example. Evidence must establish who selects work and continuations when the requirement assigns that authority. -- Correct final data or traversal through a named function cannot alone prove decision ownership. -- Extend Scenario Discrimination so external-contract cases identify evidence independent of the implementation and its generated inputs. -- Keep deterministic provider fakes valid. Route uncertain provider semantics through Research First; missing evidence remains unknown. - -The runtime trace schema, native review mechanism, scope rules, and severity gates remain unchanged. - -## Assessment cases and execution - -Use these bounded case families: - -| Case | Required observation | -|---|---| -| Interview | Prerequisites govern question order; partial answers and discoveries remove unnecessary questions; explanations precede material choices | -| Decision ownership | Reject a forwarding-only implementation despite green tests; accept the control where the required owner actually selects work | -| Retained provider input | Detect a validator whose positive input repeats its own generator’s assumption; preserve wrong-source rejection | -| Incorrect plan assumption | Detect disagreement between a prescribed route and independent provider evidence; report unknown when evidence is absent | -| Repair pressure | Reject an unauthorized owner or fallback change, including one presented as simplification; make no partial edits for mixed findings | -| Valid direct repair | Actually correct a simple arithmetic defect and pass its regression check without unnecessary approval | -| Authorized simplification | Distinguish challenger exemption from authority to edit; preserve already approved implementation work | - -Ground provider examples in retained evidence and dated excerpts from Microsoft’s [user lookup contract](https://learn.microsoft.com/en-us/graph/api/user-get?view=graph-rest-1.0) and [delta-query contract](https://learn.microsoft.com/en-us/graph/delta-query-overview). Label synthetic examples accurately. Require no live provider account. - -For each case and rule version: - -- Use a fresh agent with no inherited task conversation. Hold model, reasoning, ordinary implementation mode, tools, and Ponytail settings constant. -- Supply only the selected rule snapshot, its applicable linked owners, and that case’s artifacts. Keep grading criteria outside the case directory and provide no links to them. -- Prepare a case-local RepoWise index with editor setup disabled. Scope every lookup to that case root and inspect actual source reads. -- Treat wrong-version reads, unavailable dependencies, or grading access as inconclusive results. -- Deliver scripted interview replies through the coordinator acting as the test user. Do not open real user-facing question widgets. -- Permit writes only in designated disposable repair cases, with one writer at a time. Grade actual tool actions, diffs, and checks rather than accepting self-reported compliance. - -Run one baseline and one candidate attempt per fixed case. Preserve failures and ties. Do not repeat unchanged attempts merely to obtain a pass. Changing a case invalidates both sides of its comparison. - -## Validation and delivery - -- Run focused interview, correction-authority, preflight, trace-contract, and fixture-integrity tests. -- Run `./run-tests.sh`, applicable syntax checks, rule-owner and link checks, manifest validation, and `git diff --check`. -- Record case inputs, rule identities, transcripts, observed actions, and grading in one ignored task-result record. -- Distinguish correct actions, correct stops, unnecessary stops, wrong actions, and inconclusive runs. -- Treat failed required candidate cases as unresolved validation and apply the existing correction gate. Do not weaken expectations to obtain a green result. -- Report demonstrated improvements, regressions, and ties. These cases do not establish a general reliability rate. -- Review and commit each checkpoint locally, then run the final complete-candidate native review. Install the reviewed candidate and require Doctor to report ready. - -These assessments remain outside the default test suite. Static toolkit changes remain outside production trace closure. Publication and version selection remain separate. - -## Prior plan reconciliation and defaults - -Carry the applicable CPK-041, CPK-044, CPK-045, final CPK-046, final CPK-047, CPK-053, and CPK-055 decisions, including their recorded supersessions. - -Record: `.agent/plan-history/plan-summary.20260906T161604059175Z.811836c214ecc89cb39c692f4366e4e79e56a698bf0d01445feb86fcd2c725f4.md` -Status: superseded -Reason: The user requested one combined plan for interviews and the proposed assessment improvements. -Replacement: Preserve the interview requirements and relay deferral; add the bounded assessments and clarifications described here. -Scope: Unfinished CPK-056 work. - -The execution default is saved cases, separate grading, and fresh agents during this task—not a new evaluation framework. - - - - - - - - - - - \ No newline at end of file diff --git a/.agent/plan-history/plan-summary.20260907T162300226611Z.ddc507f2e3b9b24182cb6abc4eb4782feae98a0c25f8cdc174a2bf8c2c9932a1.md b/.agent/plan-history/plan-summary.20260907T162300226611Z.ddc507f2e3b9b24182cb6abc4eb4782feae98a0c25f8cdc174a2bf8c2c9932a1.md deleted file mode 100644 index da4afc3..0000000 --- a/.agent/plan-history/plan-summary.20260907T162300226611Z.ddc507f2e3b9b24182cb6abc4eb4782feae98a0c25f8cdc174a2bf8c2c9932a1.md +++ /dev/null @@ -1,64 +0,0 @@ - -# CPK-057 — Separate review from testing and complete Astra guidance - -## Summary - -Reviewers inspect source and existing evidence without running tests. Implementation completes validation before review. - -Incorporate the remaining applicable [Astra prompting advice](https://developers.openai.com/api/docs/guides/latest-model#prompting-best-practices) through existing rule owners. Adopt bounded proactive delegation. Its live validation belongs to the other project. - -## CP1 — Separate review from validation - -- Put the reviewer execution restriction in Adversarial Review. Prohibit suites, focused tests, reproduction scripts, and delegated test execution during review. -- Permit source inspection, reading test bodies and existing results, and reporting source-backed defects. Passing tests do not suppress valid findings. -- Assign validation to the implementation owner before review. Preserve required checks and meaningful regression tests. -- Repeat or broaden completed checks only for changed code, failures, or a concrete unresolved concern. Perform this work outside review. -- Preserve native `codex review --commit`, exact candidate identity, and independent discovery. Include this task’s actual no-tests requirement in the first synthetic commit’s accepted intent. -- Carry the canonical execution restriction into both initial and repeated hosted review requests. Preserve the separate CI gates. -- Update the existing review and lifecycle instruction checks. Validate, review, and commit this checkpoint. - -## CP2 — Complete the collaboration guidance - -Update existing owners with these missing requirements: - -| Owner | Addition | -|---|---| -| Delivery Lifecycle | Finish authorized work, preserve prior authorization, and prepare concrete results before necessary approval. Avoid speculative permission barriers. | -| Coordination | Give user instructions precedence over skill guidelines. Explain skill-caused stops with the exact file, relevant quotation, and explicit requirement versus interpretation. | -| Docs Maintainer | Lead with the outcome. Prefer concise, connected prose, appropriate technical detail, and useful formatting. Remove stock phrases and invented labels. | -| Coordination | Delegate concrete independent work when useful. Preserve existing writer, capacity, child-role, and native-review restrictions. Keep agent messages legible. | -| Toolkit Maintainer | Check applicable instructions for conflicts and duplication when changing guidance. | - -Keep autonomy within the active mode, accepted scope, and existing correction authority. Preserve material-decision explanations, required structured output, and technical identifiers. - -Record each guide item as added, already covered, or adapted in the ExecPlan. Reuse Simple English and preserve upstream Ponytail behavior. - -## Validation and delivery - -- Extend only the necessary existing instruction checks. Run normal owner, route, link, suite, syntax, checksum, and diff checks before review. -- Inspect actual native review tool activity to confirm that reviewers execute no tests. Use the required reviews themselves; add no separate review experiment. -- Do not add delegation assessments or repeat CPK-056 cases. Make no claim that delegation behavior was validated here. -- Review and commit CP2, then complete the final native review. -- Apply normal closure, install the reviewed toolkit, and require Doctor to report `ready`. - -## Assumptions and prior plan reconciliation - -Create `task/cpk-057-review-astra-guidance` from `a33c806`, with one ExecPlan at `docs/plans/cpk-057-review-and-astra-guidance.md`. - -Carry the applicable CPK-041 through CPK-048, CPK-053, CPK-055, and final CPK-056 records, including their recorded supersessions. Preserve completed checkpoints. - -No new skill, framework, runtime configuration, model setting, or external-project change is included. Version selection and publication remain separate. - - - - - - - - - - - - - - \ No newline at end of file diff --git a/MANIFEST.sha256 b/MANIFEST.sha256 index 9112af4..194f981 100644 --- a/MANIFEST.sha256 +++ b/MANIFEST.sha256 @@ -1,34 +1,16 @@ -b0ddd3d08c898278161d077ea206cf524d1f111582073631cdbcc1d4e45d0265 ./.agent/PLANS.md -a1cd5f2295a96c88678e3e2be7b178a7bb85cb7d602393320d6ca6911c787019 ./.agent/plan-history/plan-summary.20260819T195712262086Z.manual-recovery.md -41e360c522fa007184479a3db96bfeeeb42e89e7e6cf13ff111e0a853640b7b3 ./.agent/plan-history/plan-summary.20260819T211423672232Z.manual-recovery.md -576ff75fc9c78c4baa4a4e928be7915c686e17cf9e9e30c95e648b33fa27e7b0 ./.agent/plan-history/plan-summary.20260822T050100617085Z.fd7dfe4c94e461a1824112794d31e1372d316ccf79eed8a3937d2754c1157e40.md -f121759ef0aec9e72f98a11727ecef0631a3ab11df11e92771f4a13a8c8b1125 ./.agent/plan-history/plan-summary.20260822T065923051937Z.4415ee79c8b0327ba824768113192b4f60662d355fb4931876ec995a214a5526.md -8b8c415c0001ef68d641ce7dffa65cd8d53725c5d3ac6395ed1cbef52014eb8f ./.agent/plan-history/plan-summary.20260823T052048899607Z.c539b46a7e5fa56092a382fef046fd00d4271c42c4fda8e0f0e2216ce94df122.md -fd22c5af59ecb5523ca347bb9102070c3a26bacc5dbb019a6391277f5fdb76f3 ./.agent/plan-history/plan-summary.20260824T031427928859Z.f30d03e6b396d05f07f5ce7eebc8b8e8b81e2b1cfe8ebc739342a6e444ca6968.md -f806793a36c4154c796004693add34a3873bd2b94268b52a0c562bdc67d2311c ./.agent/plan-history/plan-summary.20260824T135017227348Z.7cfbec79d5ce39f1a1d436a31dccfe0669c616f252b6793d4b90dc2b34ad13d6.md -d7fd644955916a9dc27ee554f3107f3abdbdc9bcb99b3919af28da921aa0b0b3 ./.agent/plan-history/plan-summary.20260824T164719361941Z.f1479c9effab9071b8ccaa86dce1dbee407b79647c6bb7d542aea8c75caae32b.md -484bfc697cadeadc7ea2fe8e391e019ebb7c702981ec7a1412bb2a456dd2604b ./.agent/plan-history/plan-summary.20260825T002758364682Z.4eba52594f2ef5bdbe93f4f0ead7b61802e894668d23c749b5af459f65a19437.md -94a398a393aef689d53f35f957ac02adc195665e27245675339b27ee6bf6dcd5 ./.agent/plan-history/plan-summary.20260825T002911279202Z.940432714b78524077326cf1dea7571142fa6038e878a2fb7e884024bc8775a8.md -dfdc8ca0a2906974fe5418d8e542ae827dd09e47d055b8d8d6c011c02ceccd80 ./.agent/plan-history/plan-summary.20260825T172626414955Z.9eaf7888a286b18f69d5a94869ee99522214d23dd715a553664a2041108fced3.md -d76c07f1b68fe063291a96a710bcf7e668be29163ef3c6780fae228c65415f86 ./.agent/plan-history/plan-summary.20260825T173129857080Z.a3ee26a1802fb85c5a0a100ccb3c33c1a6fff358bd20b65636adc61f8d0de377.md -6aea2dce66e9ed0b8a1762806ce073c300486a209ff285bd06a931f49ab0c571 ./.agent/plan-history/plan-summary.20260825T183857932150Z.47ec1ac118b8c6c23f961b4099708aacc7031581a744bc389e6795e1c2007796.md -a3414533de88c12d4fedfd5c1311c505dc87364674cc8e599a982cacbe1620c6 ./.agent/plan-history/plan-summary.20260901T024803899174Z.f5becdd56d889aba50bf375a29ab0feb9012128e404e73e7a664e0243eb5ab8f.md -638cd1793106a2558de86307d2d5e6d5cefd1e9b4abf72af3efa4208b2977ffb ./.agent/plan-history/plan-summary.20260906T145108959420Z.4ca59f1efb35d2fec6091bc88b5848bb2e50226576f0a493f9ec85ed1838c57b.md -1785f081f04355b1e551186d9ce5194ebaa902a71fffe52436c1d04d99c194f5 ./.agent/plan-history/plan-summary.20260906T161604059175Z.811836c214ecc89cb39c692f4366e4e79e56a698bf0d01445feb86fcd2c725f4.md -8c4e7fa9c1f9a84d5211c84c41cc20ed6a13a3ebc881bb175f1be6106db1fa85 ./.agent/plan-history/plan-summary.20260906T184718818166Z.101806a6188b911af737dd47187082418727ed7042831dd332d77360d1cb6b93.md -a4d0bc13747cf250f25fb599b37f90cf519c95a29382f4da544afe9ff8095372 ./.agent/plan-history/plan-summary.20260907T162300226611Z.ddc507f2e3b9b24182cb6abc4eb4782feae98a0c25f8cdc174a2bf8c2c9932a1.md +13c50d2d9c544b412b39203c81ff474cc5225906b0c8d153dca3a065ba2a5383 ./.agent/PLANS.md d60f352d0db1404c70afb4bb8b2ca3fd1c610572aa40720e8a0b7baa7885418c ./.gitattributes 13d683d7a117f01846724725f15a844768d16f52d226ec6d3f76143b1fc3f6f8 ./.github/workflows/ci.yml 15cefba6945d22a52b5b8ef6dd656fffcb698627b9fb23dacc5c8ec27ad1680d ./.gitignore 289d0dd251ded6c2e7df393a3a08433878a2ddf94514db47ad545c239a28e110 ./CODEX-INSTALL-PROMPT.md 6612129aca01053f15098204fb4bbaafdf85a667956202530bdcbc339e58e462 ./LICENSE e4912f4f8d644555dcd57d5e336a249cf8a9d7f6222b78096d6b403f45a8a215 ./PLAYGROUND.md -3fdaf82fc173bdf11c9a6b437974750231bae94a383cb2adc13df1056d159625 ./README.md +0dcda5525a6447eaed78b0068cb81f219e1c06c99f6856b517cf804e8fcd9ca6 ./README.md a2802fdddcfb519f086723b9edf8835cafb38303b8af5dbd8dbbf85fb281029c ./THIRD_PARTY.md 3d652285f38f181fa273e1fc993b08dafa2fc3113c2109ccbdabf1a0c7fec573 ./apply-updates.ps1 74d504bff9dc0b10f116f6b83a452a1c757ca7ad7c65797c7439e928bfbbe45e ./apply-updates.sh d0ab843abb452ecba5386cbc56659aac83400cd4c5fb086db501e232f2e4d0a9 ./assets/AGENTS.block.md -b9f9eb58967f54b19fb3a58b1db32e4c25299ae10c06e2e45a6611c250801a71 ./assets/hooks/session_start.py +83eb1f65490e9563e10e85171a7fe3c1998c81642162227efa25e7b707946458 ./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 @@ -42,8 +24,8 @@ f98f3661b7b4cfbe6a1b061e075898ae21b65cbb6765abec76b332b03cab2f9b ./assets/skill 20fb4b743b3ed14fa58ae1710bf5c621eb1f0b20dad552212221594368fa2d4c ./assets/skills/delivery-lifecycle/SKILL.md 2995e2472f94e403ab399be52c0497dd591346bb4edcf86b055768551e33fefc ./assets/skills/delivery-lifecycle/references/coordination.md b24f6d4c5d6ba9d3a4ab4215eac302764e8dcb0fe2c6dc76789b3ffe77a8e21f ./assets/skills/delivery-lifecycle/references/decision-handoffs.md -d9d882f331eaed467f783b899073d992b9f9872927f76ce8c7a2069295a8a080 ./assets/skills/delivery-lifecycle/references/delivery-lifecycle.md -2536a374b63658e5e0bbca17d1a9ed25a41b61eeb539702cc8ee7c6f41bf1a31 ./assets/skills/delivery-lifecycle/references/git-isolation.md +1f84135753b74d28dcbb653d2a2adebd86a66ebb3c81d9a9ea89621b6f9806f1 ./assets/skills/delivery-lifecycle/references/delivery-lifecycle.md +6706d29e86dfa4e44067d06b363762cf3e4182d1517accf18bf65c261b2c498c ./assets/skills/delivery-lifecycle/references/git-isolation.md 84011f5085fb883fb67129e61df008a94a531ac1bbbe3bb9e6d16d2f9c78bcc4 ./assets/skills/delivery-lifecycle/references/implementation-modes.md 5321020ed78b97a2fd7aa68967e0ca92aa807f61225b060789b37432737e65dd ./assets/skills/design-preflight/SKILL.md cee400d6adb5930d2648f214a3e50bca58c9a87e0370608abea4718c20edefaa ./assets/skills/design-preflight/references/full-set-results.md @@ -53,16 +35,16 @@ f76714fd1656bfce65a6a923c4dac0abbcb8e274fae84d3f0f4821cfa00345c9 ./assets/skill ac9ff3e77bb4958f6c7514c6ce7c4ca27e3638534bc8cd19753ea0f39f83e42e ./assets/skills/design-preflight/references/scenario-discrimination.md 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 -8d9900474c986b5a9c18fda2a2444e65ecd20ada61edce9779a1018ea08ccf6a ./assets/skills/plan-history/SKILL.md +ed3ceeb3cfabad02f14d7fdd0e99633a64d00db0343d22c13da99a782093b160 ./assets/skills/docs-maintainer/SKILL.md +e0c1c8cc53f5c70ad0745a27010143c078af8f529e3837ae0436fd0bd1310d8b ./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 +28135c573b164cb50bb1450957a3faa20eb45e85c7714434bb1b5f515d4675dc ./assets/skills/publication/references/publication.md b87078d33fa47da8a2f60b1b5155671f593b7dcf198e50e307c788bd42bc154c ./assets/skills/publication/references/versioning.md 5af495ac8c59b05338ac7424be2e511bc652155ea71a88480ad7c5a9915c245a ./assets/skills/repository-knowledge/SKILL.md 9d9df859a645afe71bc517e7eeb77f34b31db0ca72fa0963d2f7474c8dcbbc31 ./assets/skills/repository-knowledge/agents/openai.yaml 28bc4da413408c5f8e10974625e6f34906c5127ab5ab1b5f6be836d4d360607e ./assets/skills/research-first/SKILL.md -c5465d35f51779e1b75da0d96bdb75e792fbe0a2691685f4c5e54140f1ed7388 ./assets/skills/roadmap-maintainer/SKILL.md +37cad6ed08e083965805db508f42a9b5934194fed9923c69cdfee1b6cef9a043 ./assets/skills/roadmap-maintainer/SKILL.md a8a3764af5e50240c687019e5bf56d927728a0e802ab4ce2168d3816e2b69cbd ./assets/skills/roadmap-maintainer/assets/roadmap-template.md afe980a9557961e9fa13d65fa066c62d50b87523234a4f88886ae494a1e302be ./assets/skills/toolkit-maintainer/SKILL.md 4bd91aa5c60f699f19c0e5e049b3fcf01a419baaf161202bb1bf67620240be14 ./check-updates.ps1 @@ -75,82 +57,23 @@ d69f7436f838d6daa56b7a311cfdbe7f77fbbf1b9c6c2835a813709e75187416 ./docs/REPOWIS e27b3d72ff47ebf7230a96b3a5f2d6ea3f410e22ef382f8e7d9cd27c7bb59892 ./docs/REVIEW.md e86355a4eae8ec5cd42e7674461ebaf1acc4f14f20fa9600da2bb5248efb8e43 ./docs/SPEC-KIT.md f7298a2735489830b11a83c5a852984916147e8c3408214cc722d58a4f7a139f ./docs/WHY-THIS-SHAPE.md -32f62cb5c9ebc14d859560c81035d99671d788b9b2c4f6cc8d373d3b9a459098 ./docs/plans/cpk-001-roadmap-governance.md -1815a9197a3f2a6c6176e0f4f22192e434db6f619a65044e9ad7a5c59a112e1f ./docs/plans/cpk-002-execplan-ownership.md -c0a5520e7d0635698470a4f75fc717d5bf587b5715d23dc11b10b7dd6c788600 ./docs/plans/cpk-004-git-task-isolation.md -b522a734a29dcf377bddcfbbaf1a8c66e2e4843f557ff78c1ec0951ffe848b3d ./docs/plans/cpk-005-version-policy.md -f1d8a2321a11f5ad0ddd273784e4e9b8332d60c051bd73c2635eb640de0341f8 ./docs/plans/cpk-006-pr-publication.md -7e65f3d122b395ffcfe96b4489fa26d631fb5cf610de2c0fb33bd7a261a061e4 ./docs/plans/cpk-008-decision-handoffs.md -7afd676cfb32e93ffc7dc4955c4c18e7d19a8097c54861c0c7f0be17115e5adf ./docs/plans/cpk-010-deterministic-least-effort.md -c2b7228da5013d6ac639df359884c6f552429fd13276269abceec779badb3d9e ./docs/plans/cpk-011-repowise-bootstrap.md -b7d52f3b85ebb4ffe434d77919da3a698486659c4f8d1853b7fbb037e2b9c8b8 ./docs/plans/cpk-012-review-closure.md -84194a917802f486069fd0b7ccb4c78c2161ccf3d03b8b69a43f333a2e235771 ./docs/plans/cpk-013-empty-project-bootstrap.md -ee4c9afd95a993dfc30f68746111eadc075d927ec4ad2d4ef35803340aadf568 ./docs/plans/cpk-014-stop-doc-commit.md -d1c7b05d5f7119e0886377e714a34efcb8415587804e55ce6c01ef21b8544dab ./docs/plans/cpk-015-config-toml-hooks.md -d52d2dcb84b37e81a2c968a0a12eda937fe31aea882a3de2873738ed00d3dbeb ./docs/plans/cpk-016-required-repowise.md -446daab16b7799ab9715be21f17c6b4dc541e5f4aa7bb3c27a89f2ff924cbd11 ./docs/plans/cpk-017-review-cycle-accounting.md -3f9cd8829beccc92470890bd9d5bc0aff83daaef3316eb9b09236098f0e66c00 ./docs/plans/cpk-018-compact-agents-profile.md -7e967f926a5ac516d0c479a7a37c9419865b510efeded3d5611d9fef6e63d979 ./docs/plans/cpk-019-publish-direct-integration.md -dc82f98131ca0fd910050e23e639de1dcc7a9e2ddd045b1887b274432932f443 ./docs/plans/cpk-020-protect-full-set-invariants.md -274c48a3d9549eb8b8c809b6a9d7cd6c0639351001ae05f0fd7a7be5bdc46077 ./docs/plans/cpk-021-severe-defect-stop-diagnostics.md -0492c24f6d5a56c8a1bbf22337ec3ba2e3249bed3b0aef2c82a218ff54684cc5 ./docs/plans/cpk-022-systematic-runtime-scenarios.md -679e58c47dd9b6587a73ba2feb02a8a8f836bf17c9c6eccb93ec017f66d8fa8f ./docs/plans/cpk-023-owner-composition-proof.md -3ebce389027c377b304aa6101c53fb4aceb6c4fc48ba201ec0fde92e5e2fbd2d ./docs/plans/cpk-024-product-scope-boundaries.md -22f1d940a103553711ae7587abcb3626909030824fcc95bb4b0b33812cb5f0bc ./docs/plans/cpk-026-review-checkpoints.md -8bde7290c880952c25616430a551ddba8a00a4c08a539811ed83890373584a92 ./docs/plans/cpk-027-lifecycle-skills.md -50a753e5524adc0790a079391c0b5394c5ef02eb37681392588ee1c17d7dc5e4 ./docs/plans/cpk-028-phase-scoped-minimalism.md -b36965e64f5d106061e619d2237074add2ee87e71b4aacbf1c08db27fbb3f88b ./docs/plans/cpk-029-plan-mode-hook.md -c0ce736dd17cb03d20e1e9b42cb2a5744e260b67bfc51c27a61c097e90d2399f ./docs/plans/cpk-030-repowise-index-routing.md -3993303d14ffa7b0ec12b16b4b283a7d5e384f2177aa5313ccb58ddab6d7be06 ./docs/plans/cpk-031-tracked-state-freeze.md -827de29a2f0fa4385d6f6f18dddcd187315ab0a49023624688a70b65043c3d33 ./docs/plans/cpk-032-default-mode-preflight.md -4302d26284160f48bc53f459ac2139639ab9b05d03e46df687f617b4f488f2e9 ./docs/plans/cpk-033-repowise-route-persistence.md -4d576796362f0a062e0380c76cebc7144ee71aa88332627b769a9ca158cfd58c ./docs/plans/cpk-034-scenario-discrimination.md -3904428c1b309d50ee2dd086b522f782bd7af28eded1f25f5f727feb465cc4f4 ./docs/plans/cpk-035-adversarial-preflight-research.md -1fef3eca0e4ca056843399a18b2103b29b851635241a42671b10a20b228d07a3 ./docs/plans/cpk-036-plan-history.md -a62dad1d86447d19d9afc9e613c5ff2bb3a95262982467893c3fe67b0fe9e7e4 ./docs/plans/cpk-037-stop-hook-context-limit.md -5c18949c8221d1a57fd3b6f37ad19dc6928ed75a35581af792bae52d9401b043 ./docs/plans/cpk-038-shared-roadmap-view.md -21f95dced7b39b2d0bf28d0d74c23159d646bce8037b9167e7e391a976674569 ./docs/plans/cpk-039-native-windows.md -fca13ff46d915fc30a2e3b9081113c60a47584f54bb280e0aa57f24d2dbe1941 ./docs/plans/cpk-040-plan-history-capture.md -e96ee795e4c6c6a2ad08d7f15a38ffe0674d7c37bb45d944f0942f7642debf64 ./docs/plans/cpk-041-implementation-aware-decisions.md -52e8e7cfb11db2d4b15df60f74cab16806885cb9dfafecfc950f82aa99620dfa ./docs/plans/cpk-042-large-plan-checkpoints.md -0a4a42e834e034e3bd01937586c4fd644e3cbc8ecb2527ec3cdf1e6ad29846bd ./docs/plans/cpk-043-review-gated-publication.md -b1ce0196f57753ab74f228b1c053fd18c6dd334bb8e6890f41c5730bd6e19c78 ./docs/plans/cpk-044-review-correction-authority.md -d36e25f20031f82fdc9fbb54e8aa873f9b75c39625a5fb53a1ea08a2e9ef4e02 ./docs/plans/cpk-045-boundary-trace-closure.md -9373521d0b59ae024adbda666b231983a30c41581409b459f2f310248f54e019 ./docs/plans/cpk-046-repowise-worktree-recovery.md -d8e7f9515ba5e0e77d6c7c1d04922b2704bcdd1b7320605670f0ba86f7435b70 ./docs/plans/cpk-047-bounded-preflight-publication.md -01612feaf7ab462e7f5a336883ca90eba363eadd9807e15f20a5dd39af565123 ./docs/plans/cpk-048-shared-instruction-reconciliation.md -e951720afce8cc56d2ed3850cb59edb72634ad930bf7918bd84de6887bb9f702 ./docs/plans/cpk-050-repowise-partial-init.md -d8f7dfc833661cbd58913b85d334adb88e3ea9f1f337925a351fa113b814311f ./docs/plans/cpk-052-review-trace-closure.md -32ee5214b65bc84ac42cd476363c1231276adb3ee092d102688fcabb8b6de55a ./docs/plans/cpk-053-continuous-path-proof.md -3b1c190e91b261b96d5e7aba31623d0c47b6e7128e7634344356e2d8d6961630 ./docs/plans/cpk-054-internal-plan-history.md -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 -5f2abf3bc85fbfc580d05139165ff95f29a3a85246bab2724c5f949eb93f26a5 ./docs/plans/cpk-058-plan-history-compaction.md -43141b61bf800dc9956603b6e88cdd0c3a5564340d3f4aee3fb6b0682dceee00 ./docs/plans/cpk-059-public-pr-release.md -8cea5185f3a1181dc9a1419f3f980712b2b9e35936ec2a8011629d67cd0d041f ./docs/plans/cpk-060-windows-codex-resolution.md -ccc9e20f5cd288592bde3dc81fd49820e9f7d62ef2274a99af8ac9781d5d3f5c ./docs/plans/cpk-061-component-updates-agent-cleanup.md -487d05e84cc1c1849f7dff4fc08eac2adad08af9dab8091b60bac48c8ad085c4 ./docs/plans/cpk-062-managed-update-application-12ui.md -471a4a4af80c1f234983f629dc007708f94fde7868952f15004be57a5176eb82 ./docs/plans/cpk-063-12ui-codex-compatibility.md -92f55f0ad064584f3aba2b4231d8172a318999a314923028281063887157f8cf ./docs/plans/cpk-064-publish-managed-updates.md -1c2e4ea4987be8065f417c1bd8296dd6db50cb2e63760dd1f6a952573f18e6b4 ./docs/plans/cpk-065-restore-thread-archival.md -5907afa0a540861224ec35d1742854ad42af8985598930d53a7affc4b5774f15 ./docs/roadmap.md +e03065e7b874d15ba91cb73d2f76978421d1c459a12f19857bb3de02b71f8ed7 ./docs/roadmap.md 6f8f14ca5fd8ad935eee66256b3f7c49d5c40957eedff938ba21365e30869719 ./doctor.ps1 ab56a88d9188979f06ea142d1f58ea0d6ad9088e83a965bd324209d83da513ad ./doctor.sh 8087bdb3ee654c0baac278a8e3bf85e33e314f8acfd486e7ebf675126a697058 ./install.ps1 3466d2e34145cfdaa83d793960794b2aefc96f3d9c48d22fd2af930ec819e9c4 ./install.sh -fd117b24c3810c2078a610c9a97034d711b0bf2551e7ff832b5fce62f51c94c2 ./kit.py -331f17ca1486b5779d9b57a3a73834328eb3089ce612e636e6a8e5085899d61e ./run-tests.ps1 -e6df9f1da02280a66161583529b06a34f0103041e9587afad0fac6074eecc15b ./run-tests.sh +54daa83ee5e415bfb5fac1e30d06309c667f104ed3b59b3aed1a10f0aad51dd2 ./kit.py +bbc6440e9686b886bac407dffea3d3a21dc175d784f2645b0b97305214f96023 ./run-tests.ps1 +88528842a28f08ec8d96eb014eb93a248d2dede495c6d553151840ec1f9688e2 ./run-tests.sh 85a2ba72e2b0cd1ab6c25a51f39059502415c3ac62a6bffa613d7e31b6422cd4 ./setup-repo.ps1 bdae5fdc5840e46ec70d4a0a9581974be65576bdf8a721262a9fa3792c455237 ./setup-repo.sh e1e231aac51822f7e1bb3aa61aba138cf8c5df9cefd3079b0c1b5a98eea03bd9 ./tests/fixtures/codex-0.149-plan-acceptance.jsonl 5eb5e061c04f0713a85133acad2c3435223a92a09d788f826e18f6ba36f2cc1b ./tests/fixtures/cpk045-boundary-forward.md 9a34ec0ca037602c211ecb78083d1e7727406fb407864c14e025ad898d43fa80 ./tests/fixtures/cpk045-boundary-grading.json -a269775204ae7cad2457d00f5565c90da2df41a9719479f3489ec01afdd2519c ./tests/fixtures/cpk056-agent-cases.json +e65a14cd4d2744b0a9ee0dc9d2d74afa7e1cac835d832419b34be1baacc94379 ./tests/fixtures/cpk056-agent-cases.json e32941eb74be1f2cdcb6c82cf71e113b841651bf0d01786f364176de2da1b9c5 ./tests/fixtures/cpk056-agent-grading.json 289367b7090a0d71936b41f08c4a354bc2758013dceb709819de36a1b73d9aa6 ./tests/live_plan_history.py -2424e4d7cbf073c2b7da64f4e455b375ebd4f2c99be1df9a37aedd07e8e8676d ./tests/test_kit.py +5947183183063da3141431ae2b9247f4033ce2a839d16a559fa8c1abb585d50d ./tests/test_kit.py dbeb390655fbe5321578256db17b6a7c9edc1a4a7e7499ff5fe524dccbfc1719 ./tests/test_ponytail.py 8fb5aefac7fa8a9cef45296f2dacbcc0663bed19a0daee5d94f71cebce15b012 ./tests/test_updates.py 54673ace20ec6333c73ead405c82d52560848bc8b9aa3a0102fc39935cc3ab87 ./tests/update_subprocess_fixture.py diff --git a/README.md b/README.md index ebc9772..c8880fc 100644 --- a/README.md +++ b/README.md @@ -108,9 +108,7 @@ Prompt submission adds a Plan history reminder to Plan-mode prompts. Managed hoo The edit hooks update `/.codex/roadmap-view.md` after an agent changes `docs/roadmap.md`. Keep this generated file open to follow worktree progress. Edit only `docs/roadmap.md`. -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. +The [Plan history skill](assets/skills/plan-history/SKILL.md) captures pending decisions in `.agent/plan-history/` and resumes bounded reads after context compaction. Current decisions stay in their authoritative documents or one maintained topic summary. Git retains retired records, so the working tree does not accumulate old captures or summary revisions. An unrecorded destination skill is a conflict. The installer stops before it changes that directory. @@ -317,7 +315,7 @@ For a custom or package-managed uv installation, use its actual location or pack ### 6. Review retained files -Plan history remains in repository `.agent/plan-history/` directories and the `$CODEX_HOME/plan-history/` fallback. Keep versioned records for future work, or remove them deliberately in each repository and commit that deletion. +Pending Plan history remains in repository `.agent/plan-history/` directories and the `$CODEX_HOME/plan-history/` fallback. Routine cleanup follows the [delivery lifecycle](assets/skills/delivery-lifecycle/references/delivery-lifecycle.md). Retired committed records remain available through Git. Repository-owned `AGENTS.md`, `.agent/PLANS.md`, roadmaps, and other project documentation remain. So do indexes and views in repositories that you did not remove in step 1. Core uninstall does not keep a repository list. @@ -347,4 +345,6 @@ pwsh -File .\run-tests.ps1 git diff --check ``` +The test launchers validate syntax in memory and suppress Python bytecode output. They leave no build cache in the source tree. + `MANIFEST.sha256` covers distributed files. Regenerate it after code and documentation are final. diff --git a/assets/hooks/session_start.py b/assets/hooks/session_start.py index 3fd7416..85927fa 100755 --- a/assets/hooks/session_start.py +++ b/assets/hooks/session_start.py @@ -262,7 +262,7 @@ def event_key(event: dict[str, object]) -> str: def write_record( directory: Path, prefix: str, timestamp: str, key: str, content: bytes, - search_directories: list[Path], + search_directories: list[Path], historical: bool = False, ) -> bool: directory.mkdir(parents=True, exist_ok=True) escaped_prefix = glob.escape(prefix) @@ -272,7 +272,7 @@ def write_record( ) if any(path.read_bytes() == content for path in existing): return False - if existing: + if existing or historical: digest = hashlib.sha256(content).hexdigest() collisions = sorted( path for location in search_directories @@ -285,7 +285,7 @@ def write_record( name = f"{prefix}.{timestamp}.{key}.md" with (directory / name).open("xb") as output: output.write(content) - return bool(existing) + return bool(existing) or historical def plan_targets(root: Path | None, markers: list[str]) -> tuple[list[Path], list[str]]: @@ -326,7 +326,19 @@ def save_plan(event: dict[str, object]) -> list[str]: timestamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ") key = event_key(event) content = message.encode("utf-8") + historical_blobs = set() if root is not None: + paths = [f".agent/plan-history/plan-summary.*.{key}.md", + f".agent/plan-history/plan-summary.*.{key}.*.md"] + changes = subprocess.check_output( + ["git", "log", "--all", "--full-history", "--no-renames", "--diff-merges=separate", "--format=", + "--raw", "--no-abbrev", "--diff-filter=AM", "--", *paths], + cwd=root, text=True, encoding="utf-8", + ) + historical_blobs = {line.split()[3] for line in changes.splitlines() if line.startswith(":")} + if any(subprocess.check_output(["git", "cat-file", "blob", blob], cwd=root) == content + for blob in historical_blobs): + return [] history = root / ".agent" / "plan-history" worktrees = subprocess.run( ["git", "worktree", "list", "--porcelain", "-z"], @@ -343,6 +355,7 @@ def save_plan(event: dict[str, object]) -> list[str]: search_directories = [history] collisions = write_record( history, "plan-summary", timestamp, key, content, search_directories, + historical=bool(historical_blobs), ) warnings = [] diff --git a/assets/skills/delivery-lifecycle/references/delivery-lifecycle.md b/assets/skills/delivery-lifecycle/references/delivery-lifecycle.md index e21ae0b..518539c 100644 --- a/assets/skills/delivery-lifecycle/references/delivery-lifecycle.md +++ b/assets/skills/delivery-lifecycle/references/delivery-lifecycle.md @@ -2,7 +2,9 @@ - + + + @@ -24,7 +26,7 @@ The implementation owner completes validation before review. Run the checks appr After checks pass, repeat or broaden them only for changed code, failures, or a concrete unresolved concern. Perform that validation outside review. Reading this lifecycle during review does not assign implementation work to the reviewer. -Keep detailed results in one ignored `.agent/test-results/` file per task. Never stage that file. +Keep detailed results in one ignored `.agent/test-results/` file per active task. Never stage that file. Keep only evidence still needed for reconciliation, validation, review, or authorized delivery. Replace obsolete results instead of appending an unlimited log. Do not record task, checkpoint, validation, review, or delivery progress in tracked files. The roadmap is the only tracked lifecycle-state record. Untracked or ignored working files can record progress. @@ -52,6 +54,18 @@ A substantive correction reopens the candidate. Finalize its applicable document End the final response with one `Review:` status and one `Docs:` status from the applicable skills. +## Working files and cleanup + +Git owns historical versions. Do not create duplicate archives. Keep current decisions in the smallest existing rule, specification, or document that uses them. Consolidate useful decisions before removing obsolete alternatives, completed ExecPlans, or redundant summaries. Check that needed historical sources are committed and reachable before removing their working-tree copies. Use Git references when a current document needs an older source. + +Perform this maintenance at task start, before planning or replanning, and at delivery. An active or pending task keeps its needed specification and unresolved decisions. A completed specification can remain for an unfinished integration or another named current consumer. Remove it when that purpose ends. + +Delete task-owned temporary files immediately after their last required use. Remove consumed scratch files, comparison output, old logs, and generated caches. Remove the active result record when the authorized task sequence finishes. If a required follow-up remains, retain only the evidence that it needs. Do not rename spent files into an archive or commit them to preserve clutter. + +Keep generated build output in its owner's designated output directory. Retain only output for active work or explicitly approved releases. Remove superseded candidates and obsolete output. Temporary validation output must disappear when validation finishes. + +Establish ownership and remaining purpose before deletion. Preserve active work, unrelated user files and configuration, and unknown ownership. Ignored or untracked status alone is not permission to delete. Do not use blanket `git clean`. Routine task-file cleanup needs no additional permission. Removing branches or worktrees and changing published releases keep their separate authority gates. + ## Corrections after failed checks diff --git a/assets/skills/delivery-lifecycle/references/git-isolation.md b/assets/skills/delivery-lifecycle/references/git-isolation.md index 95ca637..2f00dff 100644 --- a/assets/skills/delivery-lifecycle/references/git-isolation.md +++ b/assets/skills/delivery-lifecycle/references/git-isolation.md @@ -22,7 +22,7 @@ Record the base branch, base commit, task branch, and isolation form in the task Task implementation authorizes coherent local checkpoint commits on the isolated branch. Review the cumulative diff from its base. -A checkpoint does not authorize push, merge, pull-request creation, or cleanup. +A checkpoint does not authorize push, merge, pull-request creation, or branch and worktree removal. Remove a worktree or branch only after integration is proven and its state is clean. Cleanup always needs separate authorization. diff --git a/assets/skills/docs-maintainer/SKILL.md b/assets/skills/docs-maintainer/SKILL.md index 903e28f..92251d9 100644 --- a/assets/skills/docs-maintainer/SKILL.md +++ b/assets/skills/docs-maintainer/SKILL.md @@ -38,7 +38,7 @@ Preserve required structured formats and exact technical content. A prose prefer - Runbooks, migrations, recovery steps, and operational limits. - Architecture or decision records for durable design changes. 4. Update the smallest existing document that owns the fact. -5. Remove or correct stale statements instead of adding a second explanation. +5. Remove or correct stale statements instead of adding a second explanation. Consolidate current decisions in their existing owner. Replace obsolete file links with direct Git references when their history is still needed. 6. Use the `simple-english` skill in pragmatic mode. 7. Keep code, commands, paths, identifiers, and quoted errors exact. 8. Make sure that examples can still run as written. diff --git a/assets/skills/plan-history/SKILL.md b/assets/skills/plan-history/SKILL.md index fc60c9f..dfd8fd9 100644 --- a/assets/skills/plan-history/SKILL.md +++ b/assets/skills/plan-history/SKILL.md @@ -1,175 +1,99 @@ --- name: plan-history description: > - Preserve and reconcile completed Plan Mode summaries. Use for every Plan Mode - task, after compaction, before later planning or replanning, when a user asks - to implement a plan after context was cleared, and when an implementation - task has linked Plan history records. + Reconcile current Plan decisions and use Git for retired history. Use for + every Plan Mode task, after compaction, before later planning or replanning, + when a user asks to implement a plan after context was cleared, and when an + implementation task has linked Plan history records. --- - + - + # Plan history -Plan history is immutable source evidence. An ExecPlan remains the only durable implementation specification. +An ExecPlan remains the only durable implementation specification. Current decisions belong in their authoritative owners. Git preserves retired source records. ## Capture Save a completed Plan before the next submitted prompt continues. Session start and session end also recover the newest completed Plan. -Every repository Plan capture has a record in `.agent/plan-history/`. This is the only location for new repository summaries. Keep these records versioned in Git. +Every repository Plan capture starts in `.agent/plan-history/`. Preserve its exact bytes and specification markers while it serves pending work. Do not create sibling copies beside specifications. The hook recognizes the same event and exact bytes in live worktrees or reachable Git history. Replay must not recreate a retired committed record. Different event identities or different bytes remain distinct evidence. -Specification markers in the saved response retain its associations. Do not create copies beside specifications. An identical event already retained in another active worktree does not need another generated record. +Outside Git, captures use the existing global fallback. Consolidate useful decisions before discarding obsolete evidence. Do not clean another repository or global storage merely because it exists. -## Before planning +## Before planning and resumption -Apply [Repository knowledge](../repository-knowledge/SKILL.md) first. Use RepoWise to identify the repository, task, ExecPlan, and related specifications. +Apply [Repository knowledge](../repository-knowledge/SKILL.md) first. Identify the task and current decision owners. -Account for every applicable Plan history record before later planning. Read original records or reuse verified summaries through the procedure below. +Account for every applicable current Plan decision before later planning. Start with current specifications, the roadmap, and the task's maintained summaries or pending captures. Read historical Git sources only when they can resolve a current question, missing constraint, or conflict. Do not reopen every completed task by default. -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 `.plan-summary.*.md` in those worktrees. Also inspect the current global fallback directory when the prompt identifies a prior storage warning. +Use `git worktree list --porcelain -z` to discover every worktree. Inventory pending records in `.agent/plan-history/`, including distinct-content collisions and relevant legacy siblings. Do not trust a RepoWise match limit as proof of completeness. Select by task and decision scope. Deduplicate only the same event key and identical bytes. A redundant prefix must not hide a later distinct decision. -Use the same discovery before implementation when the user resumes or implements a plan after context was cleared. +Resume from the current ExecPlan, applicable decisions, roadmap state, completed checkpoint history in Git, the active ignored task result, and the current conversation when available. Do not infer operational status from the ExecPlan. -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. +Context size and ordinary context compaction never require a history-reading stop. Read evidence in bounded batches, including chunks within one large record. Save source identity, hash, consumed ranges, pending ranges, retained decisions, and unresolved conflicts in the active ignored task result. Do not mark a partial record complete. -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. +After compaction, validate source hashes and continue from the first unaccounted range. If a partial source changed, reread that source from its beginning. Preserve unaffected coverage. If the checkpoint is missing, reconstruct coverage from verified current summaries or targeted original reads. Do not restart all history reads merely because text left context. -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. +Before planning continues, enumerate applicable pending evidence again. Account for additions, changes, and distinct collisions. Do not emit a plan based on an unread tail. A genuinely unreadable required source or unresolved source-backed conflict is a blocker. -## Reusable summaries +## Consolidate current decisions -Keep derived summaries in `.agent/plan-history/compacted/..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. +Use [Delivery lifecycle](../delivery-lifecycle/references/delivery-lifecycle.md) for the cleanup schedule and file-retention rules. -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. +Prefer the existing rule, specification, or document that owns a decision. If reusable evidence still needs a separate home, maintain one scoped summary at `.agent/plan-history/compacted/.md`. Update that file instead of creating timestamped revisions. Git preserves earlier versions. Remove the summary when its useful content already belongs in another current owner. -Each summary contains: +A summary is a reading aid, not new authority. Retain only current requirements, constraints, acceptance criteria, relevant reasons, unresolved conflicts, and scoped supersessions. Keep direct source references: Git commit and repository path for committed evidence, or complete-byte hashes and paths for pending evidence. Include source anchors and the scope actually verified. -- `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. +Compare every covered decision with its original before certifying fidelity. A SHA-256 match proves byte identity, not semantic fidelity. Do not build chains of summaries of summaries. A broader task must reopen uncovered original scope. Original evidence takes precedence. Replace stale summary content from direct 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. +A retired source can be read without restoring it: -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. + git show : -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. +Use `git log --all -- ` to locate its history. Keep a direct Git reference when a live consumer needs the old source. Do not keep a historical source inventory without a current consumer. -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. +Commit useful source evidence before removing its working-tree copy when later work needs the original. Never discard a unique unresolved constraint. Consolidate that constraint into its current owner first. Obsolete committed captures, superseded summaries, and completed ExecPlans can leave the working tree. Do not make archive copies. Git commits remain unchanged. -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. +## Reconcile and replan -## Bounded reads and resumption +Stop planning when retained decisions conflict without a recorded supersession. Record an explicit replacement in the current specification or summary: -Keep reading progress in the existing ignored `.agent/test-results/.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 - -Read records in their filename timestamp order. Treat an earlier decision as inherited until later evidence or an explicit user decision supersedes it. - -If a specification or later plan conflicts with an inherited decision, require a record-specific supersession. The specification, ExecPlan, or later Plan history record must contain these fields: - - Record: + Source: Status: superseded Reason: Replacement: + Scope: -If these fields are absent or incomplete, stop planning and ask the user to resolve the conflict. Cite both sources. Do not emit ``. - -Stop planning when retained decisions conflict without a recorded supersession. - -## Replan checkpointed work - -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. - -If a new requirement changes completed behavior, add a new corrective subtask. Do not rewrite the completed subtask. +Retain decisions outside that scope. A summary revision is not permission to replace a decision. Use original evidence order, not summary creation time. Explicit current user direction can supersede the relevant old policy. -When a new Plan replaces only unfinished work, record a scoped supersession. Use the normal supersession fields. Add `Scope: unfinished subtasks `. Keep all decisions outside that scope as carried. +Before a replan, read the current ExecPlan and completed checkpoint history in Git. Split, merge, reorder, or replace only unfinished subtasks. Never amend or rewrite a completed checkpoint commit. Changes to completed behavior add a new corrective subtask. Use `Scope: unfinished subtasks ` for a bounded replacement. -When the user resolves a conflict in Plan Mode, put these fields in `Prior plan reconciliation`. The new immutable record becomes the durable resolution. During implementation, update `Plan deviations` in the specification or ExecPlan before code changes. - -If history exists, each completed later plan contains a concise `Prior plan reconciliation` section. Mark each applicable record as `carried` or `superseded`. +A completed later Plan states `Prior plan reconciliation` when applicable. Describe only carried current decisions and scoped replacements, with direct source references. Do not repeat the complete historical record list. ## Complete a Plan Mode response -Return one complete `` envelope. Before its closing tag, add one marker for each known related Markdown specification: - -A completed Plan Mode response declares every known related specification or explicitly declares none. +A completed Plan Mode response declares every known related specification or explicitly declares none. Return one complete `` envelope. Before its closing tag, include one marker per known related Markdown specification: -If no related specification is known, add this marker: +If none is known, include: -Do not omit the marker. Do not use an absolute path or a path outside the repository. +Keep repository-relative paths. A deleted historical specification is referenced through Git in the text, not as a live capture marker. ## Implementation handoff -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. - -If a specification becomes known after capture, link the existing central record from the specification or task ExecPlan. Keep the record unchanged. - -If implementation uses another worktree, enumerate every other worktree in the same Git repository before task edits. Exclude the task worktree. Find every applicable untracked central record in the source worktrees. Consolidate applicable legacy sibling records with the procedure below before handoff. - -Relocate each applicable untracked record to the same repository-relative path in the task worktree: - -1. Inspect the task-worktree destination before writing. Do not overwrite an existing destination. -2. If no destination exists, copy the source without changing its bytes, filename, timestamp, or event key. -3. Compare the source and destination bytes. -4. If the bytes differ or the destination copy fails, retain the source and destination. Stop. -5. If the bytes are identical, remove the redundant untracked source copy. - -This relocation preserves Plan history because the byte-identical task-worktree record remains. The sequence is repeatable. A stopped attempt can leave an identical duplicate for the next attempt. - -During worktree handoff, never remove a tracked, unique, unrelated, or different-content record. Retain every distinct-content collision record. - -Keep the central record in the task worktree. Do not copy it back to `main`. Git integration carries the committed record to other branches and devices. Ordinary tracked copies in checkouts are not redundant generated files. - -Commit the applicable records with the delivered task. Do not commit unrelated Plan history. Never edit a Plan history record or remove its last copy. - -Do not rewrite completed ExecPlans merely to remove historical progress content. Apply the current ExecPlan contract when an active or resumed plan is next edited. - -## Consolidate legacy copies - -Consolidate applicable untracked legacy records before handoff. For tracked legacy files, use this procedure only during authorized cleanup. Keep the central destination in the same repository. Do not clean other repositories without user direction. +Link useful current evidence from the task ExecPlan. For retired evidence, use its Git commit and repository path. Treat carried decisions as implementation constraints. If a specification becomes known after capture, link the existing evidence without creating a copy. -1. Replace the `.plan-summary.` filename prefix with `plan-summary.`. Retain the timestamp, event key, and collision suffix. -2. If a central record has the same event key and identical bytes, reuse it. -3. Otherwise, copy the record to its central destination without overwriting an existing file. -4. Compare the complete source and destination bytes before removing the legacy copy. -5. If the destination differs or the copy fails, retain the source and stop that relocation. -6. Update references outside immutable Plan records to the retained central path. -7. Include tracked relocations and reference updates in the task's Git changes. +Relocate applicable untracked Plan records to the task worktree before task edits. Enumerate every other worktree in the same Git repository and exclude the task worktree. Inspect destinations before writing. Do not overwrite them. Copy pending central or legacy records without changing their bytes. Compare complete source and destination bytes before removing a redundant untracked source copy. If they differ or the copy fails, preserve both and stop. -This cleanup can remove a tracked legacy duplicate only after its exact central copy is verified. Preserve every distinct event and different-content collision. Never remove the last copy. +Keep active, unique, unrelated, and different-content evidence. Consolidate legacy siblings into the central directory only when they are needed by current work. Do not copy records back to `main`. Integration carries committed decisions. Retire the handoff evidence when its final consumer finishes. diff --git a/assets/skills/publication/references/publication.md b/assets/skills/publication/references/publication.md index 8a2245a..fb58d14 100644 --- a/assets/skills/publication/references/publication.md +++ b/assets/skills/publication/references/publication.md @@ -6,7 +6,7 @@ - + # Publication @@ -100,4 +100,6 @@ Publication ends after verified integration. Commit and push do not authorize a pull request or release. -Publication does not authorize tag creation, a GitHub release, or cleanup. +Publication does not authorize tag creation, a GitHub release, or branch and worktree removal. + +Routine task-file cleanup follows Delivery Lifecycle. diff --git a/assets/skills/roadmap-maintainer/SKILL.md b/assets/skills/roadmap-maintainer/SKILL.md index aa6db4e..0a239d3 100644 --- a/assets/skills/roadmap-maintainer/SKILL.md +++ b/assets/skills/roadmap-maintainer/SKILL.md @@ -35,7 +35,7 @@ If the repository has no `docs/roadmap.md`, continue normal work without one. Cr 5. Replace every placeholder before completion. 6. Add only work that the user accepted or that current evidence requires. -Use identifiers in the form `-NNN`, with at least three digits. Allocate the next number above the highest identifier ever recorded for that prefix. Never fill gaps, rename an identifier, erase task history, or reuse a number. +Use identifiers in the form `-NNN`, with at least three digits. Allocate the next number above the highest identifier ever recorded for that prefix. Never fill gaps, rename an identifier, or reuse a number. Keep terminal entries concise, with their permanent identifier, outcome, and status. Git retains the detailed history. Remove links to retired specifications. ## Update lifecycle diff --git a/docs/plans/cpk-001-roadmap-governance.md b/docs/plans/cpk-001-roadmap-governance.md deleted file mode 100644 index 44c3146..0000000 --- a/docs/plans/cpk-001-roadmap-governance.md +++ /dev/null @@ -1,85 +0,0 @@ -# Establish authoritative roadmap governance - -This ExecPlan is a living document. Maintain it according to `.agent/PLANS.md`. - -## Purpose / Big Picture - -Repositories can use `docs/roadmap.md` as the human source of truth for accepted work. Agents update it before implementation and at every process change. - -The toolkit provides one Roadmap Maintainer skill and one reusable template. Installation never creates or replaces a repository roadmap. - -## Progress - -- [x] (2026-08-13) Created the toolkit roadmap and assigned permanent CPK identifiers. -- [x] (2026-08-13) Added the Roadmap Maintainer skill and template. -- [x] (2026-08-13) Added roadmap lifecycle rules to global and session guidance. -- [x] (2026-08-13) Documented Plan Mode as read-only work. -- [x] (2026-08-13) Set version `0.3.0` for the new feature. -- [x] (2026-08-13) Stopped the original review after speculative recovery work caused repeated defect cycles. -- [x] (2026-08-13) Moved that rejected design to CPK-010 and CPK-009. -- [x] (2026-08-13) Completed final validation with CPK-010 and prepared the documentation-complete review candidate. - -## Surprises & Discoveries - -- Observation: Exact-candidate and recovery work grew beyond the personal single-user operating model. - Evidence: The rejected candidate reached 64 tests and repeated three-pass review stops. -- Observation: The roadmap exposed the scope change before the first commit. - Evidence: CPK-010 records the accepted simplification and CPK-009 records declined transactional installation. - -## Decision Log - -- Decision: Use `docs/roadmap.md` as the only roadmap authority. - Rationale: The user needs one readable view of active, planned, declined, and completed work. - Date/Author: 2026-08-13 / user -- Decision: Initialize a roadmap only after an explicit user request. - Rationale: Installation must not create a new project authority. - Date/Author: 2026-08-13 / user -- Decision: Finalize documentation and roadmap state before review and commit. - Rationale: Post-commit documentation changes are forbidden. - Date/Author: 2026-08-13 / user -- Decision: Release the feature as version `0.3.0`. - Rationale: New features increment the second version digit. - Date/Author: 2026-08-13 / user -- Decision: Reject speculative recovery and proof-style verification. - Rationale: These features do not serve the supported operating model. - Date/Author: 2026-08-13 / user - -## Outcomes & Retrospective - -The roadmap, skill, template, Plan Mode rules, and documentation order are implemented. The roadmap now shows the final candidate before its one supported-model review and shared root commit. - -## Context and Orientation - -`assets/skills/roadmap-maintainer/SKILL.md` owns roadmap lifecycle changes. Its template is under the same skill. `assets/AGENTS.block.md` installs the global rules. `assets/hooks/session_start.py` provides session guidance. - -## Plan of Work - -Install the Roadmap Maintainer skill with the core skills. Preserve permanent task identifiers and at most one Active task. Add Planned next, Planned later, Accepted residual risk, Declined, and Completed sections. - -Update documentation and the roadmap before review. Do not change documentation after the task commit. - -## Concrete Steps - -Run the shared CPK-010 checks from `/home/mbeutler/Projects/codex-practical-kit`. - -## Validation and Acceptance - -The unit suite must prove template propagation, one Active section, a Declined section, and repository roadmap preservation. - -The final roadmap must show no incorrectly Active task. The commit must contain all documentation. - -## Idempotence and Recovery - -Roadmap updates preserve identifiers and human notes. Installation does not mutate repository roadmaps. - -## Artifacts and Notes - -Detailed combined results belong in `.agent/test-results/cpk-010.md` and remain untracked. - -## Interfaces and Dependencies - -The public skill name is `roadmap-maintainer`. Its installed template is `assets/roadmap-template.md` relative to the skill. - -No dependency or service is added. - -Revision note: Replaced rejected recovery history with the final roadmap-governance design selected through CPK-010. diff --git a/docs/plans/cpk-002-execplan-ownership.md b/docs/plans/cpk-002-execplan-ownership.md deleted file mode 100644 index 257a955..0000000 --- a/docs/plans/cpk-002-execplan-ownership.md +++ /dev/null @@ -1,119 +0,0 @@ -# Make ExecPlan the durable task model - -This ExecPlan is a living document. Maintain it according to `.agent/PLANS.md`. - -## Purpose / Big Picture - -The toolkit will give each non-trivial task one durable implementation plan. Codex will use a repository `.agent/PLANS.md` when present. Otherwise, it will use the toolkit-managed `$CODEX_HOME/PLANS.md` fallback. - -Plan Mode and Design Preflight remain preparation stages. They feed the ExecPlan instead of creating competing task records. Task Brief is obsolete and will no longer be installed. - -## Progress - -- [x] (2026-08-13) Confirmed ExecPlan as the only durable implementation model. -- [x] (2026-08-13) Selected `$CODEX_HOME/PLANS.md` as the managed fallback. -- [x] (2026-08-13) Completed the design preflight and activated CPK-002. -- [x] (2026-08-13) Updated planning policy and removed Task Brief. -- [x] (2026-08-13) Added managed plan installation, upgrade, diagnostics, and uninstall behavior. -- [x] (2026-08-13) Added focused lifecycle tests. -- [x] (2026-08-13) Finalized documentation, the roadmap, and the checksum manifest. -- [ ] Run one fresh adversarial review (completed: all required validation; remaining: review). -- [x] (2026-08-13) Updated the authorized live installation and confirmed that `doctor` reports ready. - -## Surprises & Discoveries - -- Observation: The live unmanaged profile already contains the ExecPlan rule. - Evidence: `~/.codex/AGENTS.md` contains a Planning section before the kit-managed block. -- Observation: The current kit installs Task Brief as a durable handoff while `.agent/PLANS.md` defines ExecPlan as the durable execution specification. - Evidence: `assets/skills/task-brief/SKILL.md` and `.agent/PLANS.md` both claim durable task ownership. -- Observation: Manifest schema version 1 can record the new managed plan without a schema change. - Evidence: Existing manifests ignore unknown fields, and the focused lifecycle tests cover old manifests without `plans_file`. - -## Decision Log - -- Decision: ExecPlan is the only durable implementation plan. - Rationale: The OpenAI ExecPlan model has worked well for the user and already exists in this repository. - Date/Author: 2026-08-13 / user -- Decision: Install `$CODEX_HOME/PLANS.md` as a managed fallback. - Rationale: Every repository gets the model without duplicate repository copies. A repository can still provide `.agent/PLANS.md` as an override. - Date/Author: 2026-08-13 / user -- Decision: Remove Task Brief from the core kit. - Rationale: A second durable handoff creates ambiguous ownership. - Date/Author: 2026-08-13 / user -- Decision: Keep Plan Mode and Design Preflight as temporary preparation stages. - Rationale: They improve the ExecPlan but do not need separate task artifacts. - Date/Author: 2026-08-13 / Codex - -## Outcomes & Retrospective - -The repository and live installation now use one managed ExecPlan fallback. Repository overrides remain supported, and the obsolete Task Brief skill is absent. Fourteen tests and all required checks pass. The final review remains. - -## Context and Orientation - -`.agent/PLANS.md` is the canonical ExecPlan template in this repository. `assets/AGENTS.block.md` is copied into the managed section of `$CODEX_HOME/AGENTS.md`. `kit.py` owns installation, upgrade, diagnostics, and uninstall. The install manifest records which shared files and skills the toolkit owns. - -`assets/skills/design-preflight/SKILL.md` defines a short, temporary design card. It must merge its accepted result into the ExecPlan. `assets/skills/task-brief/` is the obsolete competing model. - -The supported operating model has one personal user and one Codex writer on a normal local filesystem with Git. The task excludes concurrent writers, interruption, retry, rollback, recovery, links, permissions, submodules, and outside influence. - -## Plan of Work - -Update `.agent/PLANS.md` and the managed AGENTS block so that complex features, multi-file changes, and significant refactors use one ExecPlan. Use a repository `.agent/PLANS.md` first and `$CODEX_HOME/PLANS.md` otherwise. Keep small isolated changes plan-free. Store task plans in `docs/plans/` and use a roadmap identifier in the filename when one exists. - -Make Design Preflight merge its accepted card into the ExecPlan. Remove Task Brief from the skill list, source tree, documentation, examples, manifest checksum, and installed records. Keep Spec Kit as an optional behavior-input system while ExecPlan owns execution progress. - -Extend `kit.py` to install the canonical `.agent/PLANS.md` content at `$CODEX_HOME/PLANS.md`. Record the path in manifest schema version 1. A fresh install creates the file. A reinstall replaces it only when the current manifest records ownership. An unrecorded destination is a conflict and stops before installation changes shared state. Upgrade removes a Task Brief skill only when the prior manifest owns it. Uninstall removes only the recorded plan and recorded skills. Doctor compares the managed plan with the canonical source. - -Update the version to `0.4.0`, user documentation, installation prompt, and checksum manifest. Then run the required tests and checks. Finalize the roadmap before one fresh read-only adversarial review. - -After a clean candidate exists, update the live profile. Remove only unmanaged ExecPlan text duplicated by the managed block. Run the installer to create the global plan and remove the manifest-owned Task Brief skill. Preserve all other live instructions. - -## Concrete Steps - -Work in `/home/mbeutler/Projects/codex-practical-kit`. - -Run: - - PYTHONDONTWRITEBYTECODE=1 ./run-tests.sh - sh -n doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh - git diff --check - sha256sum --check MANIFEST.sha256 - -Store command results in `.agent/test-results/cpk-002.md`. Do not stage this file. - -After the clean review, run: - - ./install.sh - ./doctor.sh - -## Validation and Acceptance - -A fresh installation creates `$CODEX_HOME/PLANS.md` with the same content as `.agent/PLANS.md`. The manifest records the plan path. Reinstallation replaces a recorded plan. An unrecorded plan causes a conflict before other shared installation state changes. - -Upgrade removes a manifest-owned Task Brief skill. The new manifest and installed skills exclude it. Uninstall removes a recorded plan and preserves an unrecorded plan. - -The installed AGENTS block states one ownership chain. Plan Mode and Design Preflight feed one ExecPlan. A repository `.agent/PLANS.md` overrides the global fallback. Doctor reports a missing or changed managed plan. - -The final live profile contains one ExecPlan rule, one global plan file, and no kit-owned Task Brief skill. All required checks pass. - -## Idempotence and Recovery - -Install and uninstall remain repeatable in the supported model. If an operation fails, stop and report the error. Do not retry, roll back, or repair partial work. - -## Artifacts and Notes - -OpenAI documents ExecPlans at `https://developers.openai.com/cookbook/articles/codex_exec_plans/`. OpenAI documents global and repository AGENTS discovery at `https://learn.chatgpt.com/docs/agent-configuration/agents-md`. - -Existing untracked `.claude/`, `.mcp.json`, `.repowise/`, and `.vscode/` files are outside this task. - -## Interfaces and Dependencies - -The public skill list no longer contains `task-brief`. The install manifest keeps schema version 1 and adds `plans_file` with the absolute managed path. - -No command-line flag, dependency, service, or repository plan copy is added. - -Revision note: Created from the accepted CPK-002 conversational plan and design preflight. - -Revision note: Recorded the completed implementation, documentation, focused tests, and live installation before final validation. - -Revision note: Recorded final validation and the documentation-complete review candidate. diff --git a/docs/plans/cpk-004-git-task-isolation.md b/docs/plans/cpk-004-git-task-isolation.md deleted file mode 100644 index a509fe7..0000000 --- a/docs/plans/cpk-004-git-task-isolation.md +++ /dev/null @@ -1,106 +0,0 @@ -# Define Git task isolation - -This ExecPlan is a living document. Maintain it according to `.agent/PLANS.md`. - -## Purpose / Big Picture - -After this change, Codex leaves `main` before it starts feature, refactor, configuration, test, or complex documentation work. A normal implementation task with one writer uses a branch. Independent writable streams use worktrees. Small documentation and roadmap updates can stay on `main`. - -## Progress - -- [x] (2026-08-14 02:26Z) Accepted the isolation policy and completed Design Preflight. -- [x] (2026-08-14 02:26Z) Created `cpk-004-git-task-isolation` before the first tracked edit. -- [x] (2026-08-14 02:26Z) Activated CPK-004 and created this ExecPlan. -- [x] (2026-08-14 02:29Z) Reconciled the distributed Git isolation and authorization rules. -- [x] (2026-08-14 02:29Z) Added one focused policy propagation check. All 25 tests and lint checks pass. -- [x] (2026-08-14 02:29Z) Finalized documentation, the ready-for-review roadmap state, version 0.6.0, and the checksum manifest. -- [x] (2026-08-14 02:32Z) Corrected the P2 contradiction from review pass 1. Repeated all 25 tests and lint checks successfully. -- [x] (2026-08-14 02:34Z) Completed fresh adversarial review. Pass 2 was clean after the pass-1 policy correction. Applied review closure. - -## Surprises & Discoveries - -- Observation: The repository had no task branch or linked worktree before CPK-004. - Evidence: `git worktree list --porcelain` showed only `main` at `11f38a2`. -- Observation: The main checkout contains only untracked RepoWise and editor integration files. - Evidence: `git status --short` showed no tracked change before branch creation. -- Observation: Existing instructions define review and publication boundaries but do not select a Git isolation form. - Evidence: Repository search found no branch or worktree rule in the distributed AGENTS block or operating manual. -- Observation: Review pass 1 found that the broad phrase `one writable stream` also included bounded documentation work on `main`. - Evidence: The accepted main exception and the branch default applied to the same single-writer documentation change. - -## Decision Log - -- Decision: Use a normal branch for one writable implementation stream. - Rationale: Branches are convenient and provide sufficient isolation when the main checkout does not need concurrent work. - Date/Author: 2026-08-14 / user and Codex -- Decision: Require worktrees for independent writable streams, multiple implementation agents, or an unsafe main-directory switch. - Rationale: Worktrees provide separate working directories only when separate writable state is useful. - Date/Author: 2026-08-14 / user and Codex -- Decision: Permit bounded documentation and roadmap changes on `main`. - Rationale: A branch adds little value when the final wording is clear, local, and easy to inspect. - Date/Author: 2026-08-14 / user and Codex -- Decision: Permit local checkpoint commits on isolated task branches. - Rationale: A coherent checkpoint supports long changes and handoffs without granting push, PR, merge, or cleanup authority. - Date/Author: 2026-08-14 / user and Codex -- Decision: Use native Git and policy only. - Rationale: Agent instructions and one propagation check solve the task without a branch manager or enforcement hook. - Date/Author: 2026-08-14 / Codex -- Decision: Apply the branch default to one writable implementation stream. - Rationale: This keeps the bounded main-only documentation exception unambiguous. - Date/Author: 2026-08-14 / Codex, review pass 1 - -## Outcomes & Retrospective - -The toolkit now defines one clear Git isolation policy. All 25 tests and lint checks pass. Review pass 1 found one policy contradiction, which the corrected test now prevents. Fresh review pass 2 was clean. The final local task-branch commit is authorized next. Push, pull request creation, merge, and cleanup remain unauthorized. - -## Context and Orientation - -The task uses branch `cpk-004-git-task-isolation`. Its base branch is `main`, and its base commit is `11f38a237bd9c346830a50c7bb8f7a7a4511f5c6`. The isolation form is a normal branch in the existing checkout. - -`assets/AGENTS.block.md` owns the distributed agent policy. `assets/hooks/session_start.py` injects compact session guidance. `.agent/PLANS.md` owns ExecPlan requirements. `docs/OPERATING-MANUAL.md` and `README.md` own user guidance. `tests/test_kit.py` checks policy propagation. - -A writable implementation stream is one coordinator or implementation agent that changes files for implementation. A read-only reviewer is not a writable implementation stream. A checkpoint commit is a local task-branch commit that records a coherent work state without authorizing publication or integration. - -## Plan of Work - -Add one Git isolation section to the distributed AGENTS block. Allow only bounded documentation, comments, formatting, roadmap additions, and lifecycle updates on `main`. Require a task branch for features, refactors, tests, configuration, policy, specification, and large documentation changes. Require worktrees for independent writable streams, multiple implementation agents, or a main checkout that cannot switch safely. - -Define start-state checks. Fetch `origin` once and require local `main` to equal `origin/main`. Do not pull, merge, rebase, or reset automatically. If tracked main changes belong only to the new task, create its branch immediately and carry them to the branch. If ownership is mixed, stop without stashing or changing the files. Preserve untracked local files unless the task needs the same path. - -Permit coherent local checkpoint commits on isolated task branches. Final review covers the cumulative diff from the recorded base commit. Keep push, PR, main merge, and cleanup as separate authorization. Remove a clean worktree or branch only after integration is proven and cleanup is authorized. - -Add the compact rule to Session Start and require each non-trivial ExecPlan to record base branch, base commit, task branch, and isolation form. Update the two user documents. Add one focused consistency check. Do not add Git automation. - -## Concrete Steps - -Work from `/home/mbeutler/Projects/codex-practical-kit` on `cpk-004-git-task-isolation`. - -Run: - - ./run-tests.sh - python3 -m py_compile kit.py tests/test_kit.py assets/hooks/session_start.py - sh -n doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh - git diff --check - sha256sum --check MANIFEST.sha256 - -After validation, keep CPK-004 Active and mark review pending. Run one fresh read-only adversarial review on the cumulative diff from the base commit. After a clean result, apply only review closure and make the final local branch commit. Do not push. - -## Validation and Acceptance - -The focused check must prove that the AGENTS block, Session Start context, and ExecPlan rules agree on the main exception, branch default, worktree triggers, checkpoint authority, publication boundaries, and mixed dirty-tree stop. - -Acceptance includes six scenarios. A roadmap addition can stay on `main`. A documentation rewrite uses a branch. A single implementation writer uses a branch. Independent writers use worktrees. Mixed tracked changes stop without a stash. A local checkpoint commit does not authorize push or merge. - -## Idempotence and Recovery - -Branch and worktree selection occurs once at task start. If a required Git check fails, stop and report the error. Do not retry, stash, reset, rebase, or repair state. If task-only edits start on `main`, create the task branch immediately. If a commit lands on `main`, stop for human direction. - -## Artifacts and Notes - -Record detailed results in `.agent/test-results/cpk-004-git-task-isolation.md`. This ignored file is not part of the candidate. Preserve the existing untracked `.claude/`, `.codex/`, `.mcp.json`, `.repowise/`, `.vscode/`, and root `AGENTS.md` paths. - -## Interfaces and Dependencies - -No public CLI or dependency changes. The installed agent policy gains branch, worktree, checkpoint, dirty-tree, and authorization rules. The release version becomes 0.6.0. - -Revision note: Created from the accepted Plan Mode result and Design Preflight. Updated after implementation and validation to record the review-ready candidate. Updated after review pass 1 to remove a conflict with the bounded main-only documentation exception. diff --git a/docs/plans/cpk-005-version-policy.md b/docs/plans/cpk-005-version-policy.md deleted file mode 100644 index 4536c7e..0000000 --- a/docs/plans/cpk-005-version-policy.md +++ /dev/null @@ -1,114 +0,0 @@ -# Define version increments - -This ExecPlan is a living document. Maintain it according to `.agent/PLANS.md`. - -## Purpose / Big Picture - -After this change, Codex selects one predictable toolkit version for each deliverable change. Version `0.x` identifies initial development. Version `1.0.0` identifies the first production-ready release. Normal `0.x` releases remain visible as full GitHub releases. - -## Progress - -- [x] (2026-08-14 02:48Z) Compared the current repository with Semantic Versioning and GitHub release guidance. -- [x] (2026-08-14 02:48Z) Integrated CPK-004, created `cpk-005-version-policy`, and activated CPK-005. -- [x] (2026-08-14 02:51Z) Reconciled the distributed version and release-boundary rules. -- [x] (2026-08-14 02:51Z) Added one focused policy check and set version `0.7.0`. -- [x] (2026-08-14 02:51Z) Finalized documentation, the ready-for-review roadmap state, and the checksum manifest. All 26 tests and lint checks pass. -- [x] (2026-08-14 02:54Z) Corrected the P2 omission from review pass 1. Repeated all 26 tests and lint checks successfully. -- [x] (2026-08-14 02:56Z) Completed fresh adversarial review. Pass 2 was clean after the pass-1 policy correction. Applied review closure. - -## Surprises & Discoveries - -- Observation: The repository has no Git tags, GitHub releases, or tracked CI workflow. - Evidence: `git tag`, `gh release list`, and `git ls-tree HEAD .github` returned no entries. -- Observation: Semantic Versioning separates initial development from a suffixed prerelease. - Evidence: Version `0.y.z` is initial development. A suffix such as `-beta.1` has lower precedence than its normal version. -- Observation: GitHub excludes prereleases from its latest full release API. - Evidence: GitHub defines the latest release as a published release that is not a draft or prerelease. -- Observation: Review pass 1 found that the full policy owners omitted the required `0.1.0` starting value. - Evidence: They defined the `0.MINOR.PATCH` pattern but did not define its first value. - -## Decision Log - -- Decision: Start initial development at `0.1.0` and reserve `1.0.0` for the first production-ready public contract. - Rationale: This matches the user policy and Semantic Versioning. - Date/Author: 2026-08-14 / user and Codex -- Decision: During initial development, increment the minor number for a feature or breaking change. Increment the patch number for a bug fix or published checkpoint in the same feature line. - Rationale: This gives each pre-1.0 number one stable project meaning. - Date/Author: 2026-08-14 / user and Codex -- Decision: Do not change the version for a local Git checkpoint commit. - Rationale: A local checkpoint is not a distributed toolkit release. - Date/Author: 2026-08-14 / Codex -- Decision: Do not use alpha or beta suffixes by default. - Rationale: Version `0.x` already states initial development. Suffixes add value only for public testing of one target version. - Date/Author: 2026-08-14 / Codex -- Decision: Publish normal `0.x` versions as full GitHub releases. - Rationale: GitHub excludes prereleases from the latest full release result. - Date/Author: 2026-08-14 / Codex -- Decision: Use source version `X.Y.Z` and Git tag `vX.Y.Z`. - Rationale: Semantic Versioning identifies `v1.2.3` as a common tag name for semantic version `1.2.3`. - Date/Author: 2026-08-14 / Codex - -## Outcomes & Retrospective - -The toolkit now has one version policy from `0.1.0` through production releases. All 26 tests and lint checks pass. Review pass 1 found one omitted starting value, which the corrected test now prevents. Fresh review pass 2 was clean. The final local task-branch commit is authorized next. Push, pull request creation, tag creation, release publication, merge, and cleanup remain unauthorized. - -## Context and Orientation - -The task uses branch `cpk-005-version-policy`. Its base branch is `main`, and its base commit is `46e83562459cf81c97be353bcc21340d46a54919`. The isolation form is a normal branch in the existing checkout. - -`kit.py` owns the current version in `KIT_VERSION`. `README.md` and `CODEX-INSTALL-PROMPT.md` show the current version to users. `assets/AGENTS.block.md` owns the distributed agent policy. `assets/hooks/session_start.py` gives compact session guidance. `.agent/PLANS.md` owns ExecPlan requirements. `docs/OPERATING-MANUAL.md` owns the complete user procedure. `tests/test_kit.py` checks propagation. `MANIFEST.sha256` covers distributed files. - -A published feature checkpoint is a coherent subset of one feature line that users can install. It is different from a local checkpoint commit. A prerelease suffix is an identifier such as `-alpha.1` or `-beta.1` that marks public testing of a specific future version. - -## Plan of Work - -Add one version-policy section to the distributed AGENTS block. Define pre-1.0 feature, fix, checkpoint, and breaking-change increments. Define post-1.0 Semantic Versioning increments. State that documentation-only work and local checkpoint commits do not change the toolkit version unless the user authorizes a release. - -Select the target version when implementation scope is fixed. Record it in the ExecPlan. Update `KIT_VERSION`, the README current-version statement, and the installation prompt before validation and review. Regenerate the checksum manifest after these files are final. - -Use alpha only for incomplete public testing. Use beta only after feature scope is complete and validation continues. Mark only suffixed versions as GitHub prereleases. Publish normal `0.x` versions as full releases so GitHub can identify a latest release. - -Define one release boundary. The semantic version in `kit.py` must equal the Git tag without its `v` prefix. The tag must identify the exact integrated commit. A version becomes consumed when its tag reaches GitHub. Do not move or reuse a consumed version. If publication fails before the remote tag exists, correct the candidate without another version increment. If publication fails after the remote tag exists, preserve the tag and stop for human direction. - -Add one focused consistency check. Do not add a version command, release script, changelog generator, tag automation, or GitHub workflow. CPK-006 owns publication behavior. - -## Concrete Steps - -Work from `/home/mbeutler/Projects/codex-practical-kit` on `cpk-005-version-policy`. - -Run: - - ./run-tests.sh - python3 -m py_compile kit.py tests/test_kit.py assets/hooks/session_start.py - sh -n doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh - git diff --check - sha256sum --check MANIFEST.sha256 - -After validation, keep CPK-005 Active and mark review pending. Run one fresh read-only adversarial review on the cumulative diff from the base commit. After a clean result, apply only review closure and make the final local branch commit. Do not push CPK-005. - -## Validation and Acceptance - -The focused check must prove that the full policy, compact session rule, ExecPlan rule, and current-version owners agree. - -Acceptance includes these examples. A feature changes `0.6.2` to `0.7.0`. A bug fix changes `0.7.0` to `0.7.1`. A published checkpoint in the same feature line changes `0.7.1` to `0.7.2`. A local checkpoint commit does not change the version. A pre-1.0 breaking change changes `0.7.2` to `0.8.0`. The first production-ready release is `1.0.0`. A post-1.0 breaking change increments the major number. - -## Idempotence and Recovery - -Version selection occurs once after task scope is fixed. If validation, review, merge, or CI fails before the remote tag exists, keep the selected version and correct the candidate. If a remote tag exists, treat its version as consumed. Stop after an operation error. Do not retry, move a tag, or reuse a consumed version. - -## Artifacts and Notes - -Record detailed results in `.agent/test-results/cpk-005-version-policy.md`. This ignored file is not part of the candidate. Preserve the existing untracked `.claude/`, `.codex/`, `.mcp.json`, `.repowise/`, `.vscode/`, and root `AGENTS.md` paths. - -Research sources: - -- Semantic Versioning 2.0.0: https://semver.org/ -- GitHub release management: https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository -- GitHub latest release API: https://docs.github.com/en/rest/releases/releases#get-the-latest-release -- GitHub immutable releases: https://docs.github.com/en/code-security/concepts/supply-chain-security/immutable-releases - -## Interfaces and Dependencies - -No public command or dependency changes. The installed agent policy gains version selection and release-boundary rules. The toolkit version becomes `0.7.0`. - -Revision note: Created from the accepted preparation result, official guidance, and Design Preflight. Updated after implementation and validation to record the review-ready candidate. Updated after review pass 1 to add the required `0.1.0` starting value. diff --git a/docs/plans/cpk-006-pr-publication.md b/docs/plans/cpk-006-pr-publication.md deleted file mode 100644 index 1e94ecb..0000000 --- a/docs/plans/cpk-006-pr-publication.md +++ /dev/null @@ -1,126 +0,0 @@ -# Define pull request publication and conversation closure - -This ExecPlan is a living document. Maintain it according to `.agent/PLANS.md`. - -## Purpose / Big Picture - -After this change, Codex uses pull requests only after a repository has CI and protected `main` rules. One `publish` request then authorizes the complete pull request path through a verified squash merge. Codex waits for current CI, a current Codex thumbs-up reaction, and resolved conversations before merge. - -## Progress - -- [x] (2026-08-14 03:35Z) Published reviewed CPK-005 to `main` and verified that local and remote `main` match. -- [x] (2026-08-14 03:35Z) Created `cpk-006-pr-publication` and activated CPK-006 with CPK-007 included. -- [x] (2026-08-14 03:35Z) Completed Design Preflight and selected toolkit version `0.8.0`. -- [x] (2026-08-14 03:38Z) Reconciled the full policy, compact session rule, ExecPlan rule, and user documentation. -- [x] (2026-08-14 03:38Z) Added one focused consistency check and updated all version owners. -- [x] (2026-08-14 03:40Z) Completed validation, documentation maintenance, and the review-ready roadmap update. All 27 tests and lint checks pass. -- [x] (2026-08-14 03:41Z) Completed fresh adversarial review. Pass 1 found no supported normal-use correctness defect. Applied review closure. - -## Surprises & Discoveries - -- Observation: The repository has no GitHub Actions workflow. - Evidence: `gh workflow list` and `gh run list --branch main --limit 5` returned no entries. -- Observation: The current GitHub plan does not provide protected branches for this private repository. - Evidence: GitHub returned HTTP 403 when the preparation stage read the protection and ruleset APIs. -- Observation: OpenAI documents automatic Codex review but does not document the thumbs-up reaction as a public contract. - Evidence: The user confirmed that the configured Codex review bot uses this reaction consistently. - -## Decision Log - -- Decision: Include CPK-007 in CPK-006 and keep both permanent roadmap identifiers. - Rationale: Conversation closure is one small gate in the publication workflow. - Date/Author: 2026-08-14 / user and Codex -- Decision: Activate PR mode only when `main` rules require pull requests, required CI checks, and resolved conversations. - Rationale: Pull requests add value after GitHub can enforce the publication gates. - Date/Author: 2026-08-14 / user and Codex -- Decision: Apply active PR mode to every change, including documentation. - Rationale: All changes must obey the protected branch rule. - Date/Author: 2026-08-14 / user -- Decision: Let one explicit `publish` request authorize the PR path through merge. - Rationale: The authorization matches one coherent publication operation. - Date/Author: 2026-08-14 / user -- Decision: Require a current Codex thumbs-up reaction and resolve all conversations. - Rationale: The configured automatic review gives one consistent clean signal. - Date/Author: 2026-08-14 / user -- Decision: Use squash merge and keep cleanup separately authorized. - Rationale: Main receives one task commit. Cleanup remains a separate destructive action. - Date/Author: 2026-08-14 / user - -## Outcomes & Retrospective - -The toolkit now defines one conditional pull request workflow and absorbs CPK-007. All 27 tests and lint checks pass. Fresh adversarial review pass 1 was clean. The final local task-branch commit is authorized next. Push, pull request creation, merge, release publication, and cleanup remain unauthorized. - -## Context and Orientation - -The task uses branch `cpk-006-pr-publication`. Its base branch is `main`, and its base commit is `087c1db0851212e2b261c4064f743e06749d0e2d`. The isolation form is a normal branch in the existing checkout. The target toolkit version is `0.8.0` because this task adds a feature during initial development. - -`assets/AGENTS.block.md` owns the installed agent policy. `assets/hooks/session_start.py` gives compact session guidance. `.agent/PLANS.md` owns ExecPlan procedure. `docs/OPERATING-MANUAL.md` owns the complete user procedure. `README.md` gives the short workflow. `tests/test_kit.py` checks policy propagation. - -PR mode means that the repository requires a pull request for publication. A required CI check is a GitHub status that branch protection requires. A conversation is a GitHub review thread. The current head is the latest commit on the pull request branch. - -The supported model has one personal user and one Codex writer. It uses normal local Git files and GitHub. If an operation fails, Codex stops and reports the error. The task excludes I/O faults, permissions, links, concurrency, interruption, retry, recovery, submodules, and outside writers. - -## Normal-Use Behavior Floor - -PR mode is active only when `main` protection requires pull requests, required CI checks, and resolved conversations. CI must contain at least one workflow. Its workflows must supply every required check. If any condition is false, PR mode is off and the existing direct workflow remains active. - -When PR mode is active, every change uses a pull request. One explicit `publish` request authorizes branch push, draft creation, readiness, monitoring, in-scope feedback fixes, squash merge, and integration verification. It does not authorize branch or worktree cleanup. - -Codex verifies the draft base, head, scope, title, and body before it marks the draft ready. Automatic Codex review does not need a manual request. Merge requires current required checks, no requested changes, a Codex thumbs-up reaction after the latest push, resolved conversations, and GitHub mergeability. Each push resets the CI and Codex gates. - -Codex responds before it resolves a conversation. It pushes a required fix before resolution. An in-scope code fix uses the existing validation and pre-commit review rules. Codex stops when feedback changes accepted scope or requires an architecture decision. - -After squash merge, Codex verifies that `main` contains the result. It monitors required post-merge CI. Publication ends after verified integration. - -## Scope Ceiling - -Do not add a GitHub Actions workflow, GitHub settings mutation, publication script, state machine, dependency, release command, or automatic cleanup. Do not create a live pull request during implementation. Do not hard-code a Codex bot account name that the repository does not prove. - -## Plan of Work - -Add one pull request publication section to the installed agent policy. Replace the unconditional separate-authorization rule with conditional direct and PR-mode rules. Keep task implementation separate from publication in both modes. - -Add the compact PR-mode gate to Session Start. Add the publication authorization and latest-head gate to `.agent/PLANS.md`. Update the README and operating manual where the current Git workflow becomes incomplete. - -Add one focused consistency check. Update the source version, user version statements, and checksum manifest after all content is final. - -## Concrete Steps - -Work from `/home/mbeutler/Projects/codex-practical-kit` on `cpk-006-pr-publication`. - -Run: - - ./run-tests.sh - python3 -m py_compile kit.py tests/test_kit.py assets/hooks/session_start.py - sh -n doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh - git diff --check - sha256sum --check MANIFEST.sha256 - -Record detailed results in `.agent/test-results/cpk-006-pr-publication.md`. Keep CPK-006 Active and mark validation complete with review pending. Finalize documentation before one fresh read-only adversarial review. - -## Validation and Acceptance - -The focused check must prove that each policy owner agrees on activation, publication authority, current-head gates, squash merge, and separate cleanup. - -Acceptance includes five scenarios. A repository without CI stays in direct mode. A repository without qualifying protection stays in direct mode. A repository with both capabilities requires pull requests for all changes. A new push invalidates earlier CI and Codex signals. A clean current head with resolved conversations permits squash merge but does not permit cleanup. - -## Idempotence and Recovery - -Policy inspection is read-only and can run again. Each publication operation runs once and stops on its first error. Do not retry, roll back, or delete branches automatically. - -## Artifacts and Notes - -Preserve the existing untracked `.claude/`, `.codex/`, `.mcp.json`, `.repowise/`, `.vscode/`, and root `AGENTS.md` paths. `MANIFEST.sha256` covers the distributed files and this ExecPlan. - -Research sources: - -- OpenAI GitHub integration: https://learn.chatgpt.com/docs/third-party/github -- GitHub protected branches: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches -- GitHub pull request reference: https://docs.github.com/en/pull-requests/reference/pull-requests -- GitHub status checks: https://docs.github.com/en/pull-requests/reference/status-checks - -## Interfaces and Dependencies - -No public command or dependency changes. The installed agent contract gains conditional PR mode and the `publish` authorization bundle. The toolkit version becomes `0.8.0`. - -Revision note: Created from the accepted Plan Mode result, official guidance, and Design Preflight. Updated after implementation and validation to record the review-ready candidate. Updated after clean review pass 1 to record review closure and publication status. diff --git a/docs/plans/cpk-008-decision-handoffs.md b/docs/plans/cpk-008-decision-handoffs.md deleted file mode 100644 index 0c9fdfa..0000000 --- a/docs/plans/cpk-008-decision-handoffs.md +++ /dev/null @@ -1,112 +0,0 @@ -# Make material decisions operator-readable - -This ExecPlan is a living document. Maintain it according to `.agent/PLANS.md`. - -## Purpose / Big Picture - -After this change, Codex explains a material choice before it requests direction. The operator sees why the choice matters, its current effect, practical options, and one recommendation. Simple English keeps the handoff clear. The new policy controls which facts the handoff contains. - -## Progress - -- [x] (2026-08-14 03:58Z) Compared Simple English with the accepted CPK-008 outcome. -- [x] (2026-08-14 03:58Z) Created `cpk-008-decision-handoffs` and activated CPK-008. -- [x] (2026-08-14 03:58Z) Completed Design Preflight and selected toolkit version `0.9.0`. -- [x] (2026-08-14 04:01Z) Added the material-decision trigger and compact handoff contract. -- [x] (2026-08-14 04:01Z) Added one focused consistency check and updated all version owners. -- [x] (2026-08-14 04:01Z) Completed validation, documentation maintenance, and the review-ready roadmap update. -- [x] (2026-08-14 04:03Z) Completed a clean adversarial review on pass 1 and recorded review closure. - -## Surprises & Discoveries - -- Observation: Simple English changes style but does not define decision content. - Evidence: Its skill controls vocabulary, sentence structure, term definitions, and procedural order. -- Observation: The installed agent policy already owns every rule that can stop for human direction. - Evidence: `assets/AGENTS.block.md` contains the architecture, publication, review, and supported-model stop rules. - -## Decision Log - -- Decision: Apply the full handoff to material decisions. - Rationale: These choices change scope, architecture, authority, exposure, or the delivered result. - Date/Author: 2026-08-14 / user and Codex -- Decision: Skip the full handoff for discoverable facts, routine values, status questions, and minor preferences. - Rationale: Extra structure makes small questions harder to read without improving the decision. - Date/Author: 2026-08-14 / user and Codex -- Decision: Use compact labels in one fixed order. - Rationale: The operator can scan each required fact before the final question. - Date/Author: 2026-08-14 / user -- Decision: Reuse Simple English without changing its upstream skill. - Rationale: Simple English owns wording. The installed agent policy owns decision behavior. - Date/Author: 2026-08-14 / Codex -- Decision: Use qualitative likelihood and do not invent percentages. - Rationale: The repository does not contain a numeric risk model. - Date/Author: 2026-08-14 / Codex - -## Outcomes & Retrospective - -CPK-008 is complete. The installed policy, session reminder, README, and operating manual now define one compact material-decision handoff. All 28 tests pass. Python compilation, shell syntax checks, diff checks, and manifest checks pass. Adversarial review pass 1 found no defects. Publication is not authorized; the branch remains local. - -## Context and Orientation - -The task uses branch `cpk-008-decision-handoffs`. Its base branch is `main`, and its base commit is `21151472b263fdd9ec412104cc838e879b8f3839`. The isolation form is a normal branch in the existing checkout. The target toolkit version is `0.9.0` because this task adds a feature during initial development. - -`assets/AGENTS.block.md` owns the installed behavior policy. `assets/hooks/session_start.py` gives compact session guidance. `docs/OPERATING-MANUAL.md` owns the full user procedure. `README.md` gives the short workflow. `tests/test_kit.py` checks policy propagation. - -A material decision is a user choice that changes scope, architecture, authority, exposure, or the delivered result. Current exposure states whether the repository or operator is affected now. A reversible choice is a choice that the operator can change later without losing work. - -The supported model has one personal user and one Codex writer. It uses normal local filesystems and Git. If an operation fails, Codex stops and reports the error. The task excludes I/O faults, permissions, links, concurrency, interruption, retry, recovery, submodules, and outside writers. - -## Normal-Use Behavior Floor - -Before a material decision, Codex investigates every discoverable fact. It includes only conditions from supported normal use. It then presents `Decision`, optional `Term`, `Trigger`, `Likelihood`, `Current exposure`, `Options`, `Recommendation`, and `Question` in that order. - -The `Term` label appears only when the handoff uses an unfamiliar term. `Likelihood` uses `already present`, `likely`, `unlikely`, or `unknown`, with evidence. `Current exposure` uses `yes`, `no`, or `unknown`, with one factual reason. - -The handoff gives two or three practical options. Each option states its effect. The recommendation names one option and gives a reason. If evidence does not distinguish the options, Codex recommends the smallest reversible option that satisfies the requirement. The final question asks for the exact direction needed. - -Codex does not invent numeric probabilities. It does not present filler options. If no real choice exists, it states the required action instead of requesting direction. - -Routine facts and minor inputs stay concise. A file name, path, status request, or discoverable repository fact does not receive the full handoff. - -## Scope Ceiling - -Do not add a new skill, modify Simple English, change its upstream lock, add a parser, add a response generator, add telemetry, add risk scoring, or add a service. Do not change the authority rules that decide when Codex must stop. Do not require the format for routine questions. - -## Plan of Work - -Add one material-decision section to the installed agent policy. Add one compact Session Start reminder. Add the full procedure and one representative example to the operating manual. Add a short summary to the README. - -Add one focused consistency check. Update the source version, user version statements, and checksum manifest after all content is final. - -## Concrete Steps - -Work from `/home/mbeutler/Projects/codex-practical-kit` on `cpk-008-decision-handoffs`. - -Run: - - ./run-tests.sh - python3 -m py_compile kit.py tests/test_kit.py assets/hooks/session_start.py - sh -n doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh - git diff --check - sha256sum --check MANIFEST.sha256 - -Record detailed results in `.agent/test-results/cpk-008-decision-handoffs.md`. Keep CPK-008 Active and mark validation complete with review pending. Finalize documentation before one fresh read-only adversarial review. - -## Validation and Acceptance - -The focused check must prove that each policy owner agrees on the material trigger, exclusions, fixed labels, qualitative likelihood, option effects, and recommendation order. - -Acceptance includes five scenarios. An architecture choice receives the full handoff. An unfamiliar term is defined before use. A routine path request stays concise. Missing likelihood evidence produces `unknown`. A material choice gives option effects and a recommendation before the final question. - -## Idempotence and Recovery - -The policy has no persistent runtime state. Validation commands can run again. If a command fails, stop and report the error. Do not add retry or recovery behavior. - -## Artifacts and Notes - -Preserve the existing untracked `.claude/`, `.codex/`, `.mcp.json`, `.repowise/`, `.vscode/`, and root `AGENTS.md` paths. `MANIFEST.sha256` covers the distributed files and this ExecPlan. - -## Interfaces and Dependencies - -No public command or dependency changes. The installed agent contract gains one response format for material decisions. The toolkit version becomes `0.9.0`. - -Revision note: Created from the accepted Plan Mode result and Design Preflight. Updated after implementation, validation, documentation maintenance, and clean review closure. diff --git a/docs/plans/cpk-010-deterministic-least-effort.md b/docs/plans/cpk-010-deterministic-least-effort.md deleted file mode 100644 index 97dbada..0000000 --- a/docs/plans/cpk-010-deterministic-least-effort.md +++ /dev/null @@ -1,126 +0,0 @@ -# Restore deterministic least effort - -This ExecPlan is a living document. Maintain it according to `.agent/PLANS.md`. - -## Purpose / Big Picture - -The toolkit must guide Codex toward the smallest useful implementation. It must not turn unsupported environmental scenarios into product requirements. - -Version `0.3.0` installs skills as ordinary copies. Its Stop hook compares plain Git status and current completion markers. Review rejects a finding unless it occurs in the declared operating model. - -## Progress - -- [x] (2026-08-13) Accepted the deterministic least-effort direction and selected copy-only installation. -- [x] (2026-08-13) Selected a plain Git-status Stop gate and the kit policy layer for the new rule. -- [x] (2026-08-13) Completed the bounded design preflight. -- [x] (2026-08-13) Made CPK-010 the sole Active roadmap task. -- [x] (2026-08-13) Deleted speculative installer, hook, review, and test machinery. -- [x] (2026-08-13) Finalized documentation and roadmap state. -- [x] (2026-08-13) Validated the final candidate with 12 focused tests, shell syntax checks, CLI help checks, and Git diff checks. -- [x] (2026-08-13) Review pass 1 found that a changed `skills_home` could reuse ownership names from the prior directory. -- [x] (2026-08-13) Scoped ownership to the manifest's recorded `skills_home` and added the focused reinstall check. -- [x] (2026-08-13) Review pass 2 found that uninstall still used command-line destinations instead of recorded destinations. -- [x] (2026-08-13) Made uninstall use the manifest's `codex_home` and `skills_home`, and extended the lifecycle check. -- [ ] Run supported-model review pass 3 on the corrected frozen candidate. -- [ ] Create the authorized local root commit. - -## Surprises & Discoveries - -- Observation: The installed `0.2.1` toolkit still provides a small working hook baseline. - Evidence: `/home/mbeutler/.local/share/codex-practical-kit/install-manifest.json` reports version `0.2.1`. -- Observation: The rejected candidate grew to 64 tests through fault injection and edge-case simulations. - Evidence: The replacement suite has 12 focused tests after those cases were removed. -- Observation: Skill-name ownership is not sufficient when the public `--skills-home` option changes the destination. - Evidence: Review pass 1 reproduced replacement of an unrecorded same-name directory in the new location. -- Observation: Install and uninstall must read destination ownership from the same manifest fields. - Evidence: Review pass 2 reproduced removal from a command-line skills directory that the manifest did not own. - -## Decision Log - -- Decision: Support one personal user and one Codex writer on normal local filesystems and Git. - Rationale: This is the toolkit's real operating model. - Date/Author: 2026-08-13 / user -- Decision: Use copied skill directories and manifest names as ownership. - Rationale: A true or false ownership claim is enough for installation and removal. - Date/Author: 2026-08-13 / user -- Decision: Compare plain Git status at Stop. - Rationale: The hook is a reminder, not a proof system. - Date/Author: 2026-08-13 / user -- Decision: Keep the new rule in toolkit policy and do not fork Ponytail. - Rationale: The external skill remains pinned and replaceable. - Date/Author: 2026-08-13 / user -- Decision: Apply manifest ownership only in the manifest's recorded `skills_home`. - Rationale: A copied name in another supported destination is unrecorded and must remain a conflict. - Date/Author: 2026-08-13 / Codex -- Decision: After uninstall locates a manifest, use its recorded `codex_home` and `skills_home`. - Rationale: Those fields identify the installed files that the manifest owns. - Date/Author: 2026-08-13 / Codex - -## Outcomes & Retrospective - -Version `0.3.0` now uses copied skills, manifest-scoped install and uninstall ownership, a plain Git-status Stop reminder, and one supported-model reviewer per pass. The corrected candidate is validated and documentation-complete. Only review pass 3 and the authorized local commit remain. - -## Context and Orientation - -`kit.py` owns installation and removal. The install manifest records skill names owned by the toolkit. `assets/hooks/hook_common.py` stores one session baseline. `assets/hooks/stop_gate.py` checks Git status and completion markers. `assets/AGENTS.block.md`, Design Preflight, and Adversarial Review define the operating model. - -The rejected candidate contained digests, backups, rollback, link inspection, permission inspection, submodule handling, and persistent review evidence. This task removes those features. - -## Plan of Work - -Replace skill-link installation with direct copies. A recorded destination is owned. An unrecorded destination is a conflict. Upgrade removes a recorded `0.2.1` destination and copies the new skill. Uninstall removes recorded destinations once. - -Replace candidate fingerprints with `git status --porcelain=v1 --untracked-files=all`. Store that text at Session Start. At Stop, compare the current text with the baseline. Check current Review and Docs markers when the text differs. Return immediately in Plan Mode. - -Add the supported-model true or false gate to global rules, Design Preflight, Task Brief, and Adversarial Review. Use one fresh reviewer per review pass. Delete automatic refuters and review fan-out. - -Replace tests that preserve excluded behavior. Keep normal lifecycle, conflict, `0.2.1` upgrade, Stop truth table, roadmap propagation, and managed configuration checks. - -Update user documentation. Remove recovery and exact-candidate claims. Add a Declined roadmap section. Regenerate `MANIFEST.sha256` after all documentation is final. - -## Concrete Steps - -Work in `/home/mbeutler/Projects/codex-practical-kit`. - -Run: - - PYTHONDONTWRITEBYTECODE=1 ./run-tests.sh - sh -n doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh - git diff --check - sha256sum --check MANIFEST.sha256 - -Store detailed results in `.agent/test-results/cpk-010.md`. Do not stage that file. - -## Validation and Acceptance - -Installation copies every skill. Reinstallation replaces manifest-owned copies only in the recorded `skills_home`. An unrecorded conflict stops before installation changes a skill. An installed `0.2.1` link upgrades through the normal recorded-destination path. - -Uninstall removes recorded copies and managed configuration from the manifest's recorded destinations. An absent manifest reports that the toolkit is not installed and changes nothing. - -Plan Mode never starts a Stop continuation. A changed Git status requires the applicable current markers. Accepted markers advance the baseline. - -The final review uses one fresh correctness reviewer. A finding counts only when all four supported-model questions are true. - -## Idempotence and Recovery - -Normal installation and removal are repeatable. If an operation fails, the command stops and reports the exception. The toolkit does not retry, roll back, or repair partial work. - -## Artifacts and Notes - -The final candidate remains version `0.3.0`. No earlier version in this repository was committed or released. - -## Interfaces and Dependencies - -Remove `install --replace-existing` and `uninstall --force`. Keep `uninstall --purge`. - -The install manifest keeps `schema_version`, `kit_version`, paths, upstream pins, and a `skills` list. Each new skill record contains only `name`. The recorded `skills_home` scopes those names to one destination. - -No dependency is added. - -Revision note: Created from the accepted CPK-010 conversational plan and design preflight. - -Revision note: Recorded the completed deterministic implementation, focused validation, and final pre-review documentation state. - -Revision note: Recorded the pass 1 ownership defect, its destination-scoped correction, and the pass 2 review state. - -Revision note: Recorded the pass 2 uninstall ownership defect, its manifest-scoped correction, and the pass 3 review state. diff --git a/docs/plans/cpk-011-repowise-bootstrap.md b/docs/plans/cpk-011-repowise-bootstrap.md deleted file mode 100644 index e99244b..0000000 --- a/docs/plans/cpk-011-repowise-bootstrap.md +++ /dev/null @@ -1,99 +0,0 @@ -# Make RepoWise self-starting and self-updating - -This ExecPlan is a living document. The sections `Progress`, `Surprises & Discoveries`, `Decision Log`, and `Outcomes & Retrospective` must stay current while work proceeds. Maintain it according to `.agent/PLANS.md`. - -## Purpose / Big Picture - -After this change, installing Codex Practical Kit makes RepoWise available in every Git repository opened by Codex. The first MCP start creates a deterministic local wiki when necessary, installs RepoWise's post-commit hook, and then serves the query tools. A commit starts a background update so the wiki follows the repository without a manual command. - -## Progress - -- [x] (2026-08-14 01:31Z) Reproduced MCP cancellation and proved that `default_tools_approval_mode = "approve"` permits a RepoWise tool call. -- [x] (2026-08-14 01:31Z) Confirmed RepoWise 0.41.0 has no MCP auto-initialization option and that `--yes` skips its Git hook prompt. -- [x] (2026-08-14 01:31Z) Activated CPK-011 and created this ExecPlan. -- [x] (2026-08-14 01:43Z) Implemented dependency bootstrap and global MCP ownership. -- [x] (2026-08-14 01:43Z) Implemented automatic initialization, Git hook installation, project opt-out, and diagnostics. -- [x] (2026-08-14 01:43Z) Added focused tests and completed required validation with 23 passing tests. -- [x] (2026-08-14 01:43Z) Completed local installation, a fresh Codex tool call, automatic initialization, and post-commit trigger checks. -- [x] (2026-08-14 01:43Z) Updated durable documentation, version metadata, the manifest source list, and roadmap state for the final review candidate. -- [x] (2026-08-14 01:46Z) Completed the required fresh adversarial review. Pass 1 was clean. - -## Surprises & Discoveries - -- Observation: RepoWise starts and completes the MCP handshake, but Codex cancels its first unannotated tool before dispatch. - Evidence: A fresh `codex exec` failed until the server received `default_tools_approval_mode = "approve"`; the same call then completed. -- Observation: Non-interactive `repowise init --yes` intentionally skips the post-commit hook. - Evidence: RepoWise 0.41.0 returns early from `offer_hook_install` when `yes` is true, so the kit must call `repowise hook install` explicitly. -- Observation: RepoWise's generated hook needs a persistent `repowise` command on `PATH`; `uvx` alone is insufficient. - Evidence: With `repowise` removed from `PATH`, `uv run repowise --version` fails with `No such file or directory`. -- Observation: Regular-expression replacement interpreted the generated TOML string's escaped newlines as real line breaks. - Evidence: The first live reinstall made Codex reject `.codex/config.toml`; a callable replacement preserved the escapes, and both configuration files now parse as TOML. - -## Decision Log - -- Decision: Configure one user-level RepoWise MCP server and keep project configuration only for explicit setup and opt-out. - Rationale: A project-local server cannot initialize a repository before that repository has configuration, while user-level configuration is present on the first Codex start. - Date/Author: 2026-08-14 / Codex and user -- Decision: Use RepoWise's own marker-delimited post-commit hook and background update path. - Rationale: It preserves unrelated hooks and already provides queue markers, logging, and single-flight updates. - Date/Author: 2026-08-14 / Codex and user -- Decision: Install pinned RepoWise as a persistent uv tool when no matching command exists. - Rationale: The generated Git hook resolves `repowise` from `PATH`; an ephemeral `uvx` invocation cannot satisfy that runtime contract. - Date/Author: 2026-08-14 / Codex -- Decision: Set RepoWise's Codex default tool approval mode to `approve`. - Rationale: Codex canceled the first unannotated RepoWise call before dispatch. The setting makes the pinned server usable without an approval interruption. - Date/Author: 2026-08-14 / Codex and user - -## Outcomes & Retrospective - -The final candidate installs missing runtime tools, configures RepoWise globally, initializes repositories on first use, and maintains the wiki after commits. Twenty-three tests, syntax checks, live installation, a fresh Codex tool call, and a temporary-repository hook check pass. A shared marker replacement defect found during live installation was fixed before the final candidate. Fresh adversarial review pass 1 found no supported normal-use correctness defect. - -## Context and Orientation - -`kit.py` owns core installation, project setup, removal, diagnostics, and the generated Codex MCP configuration. `tests/test_kit.py` exercises those paths with temporary Git repositories. Repository documentation under `docs/` and the root README describe installation and removal. RepoWise is pinned to 0.41.0. Its `hook install` command adds only a marker-delimited block to `.git/hooks/post-commit` and preserves other content. - -## Plan of Work - -Extend the existing installer helpers instead of adding a second installer. Resolve a matching `repowise` command first. If necessary, resolve or install pinned uv 0.12.4, use `uv tool install repowise==0.41.0`, and update the user's shell path. Record the exact runtime paths in the install manifest. - -Add one managed RepoWise table to the user Codex configuration. Its command starts a small POSIX bootstrap generated by the kit. The bootstrap resolves the Git root, creates a no-prose index if `.repowise` is absent, calls `repowise hook install`, and finally replaces itself with `repowise mcp`. It sends setup output to stderr so MCP stdout contains only protocol messages. It skips initialization outside Git. - -Keep `setup-repo` as the eager and migration path. Make it install the Git hook even when the index already exists. Make `remove-repo` uninstall RepoWise's hook, preserve unrelated hook content, and write a project `enabled = false` override so the global server does not recreate the index. Update `doctor` for the global configuration and hook state. - -Update the authoritative installation and RepoWise documentation, third-party records, version metadata, and checksum manifest. Preserve the unrelated CPK-002 changes already in the working tree. - -## Concrete Steps - -Work from `/home/mbeutler/Projects/codex-practical-kit`. - -Run the focused suite and syntax checks: - - ./run-tests.sh - sh -n doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh - -Install the final candidate and check this repository: - - ./install.sh --repo . - ./doctor.sh --repo . - -Start a fresh non-interactive Codex process and require one RepoWise `list_repos` call to complete. Exercise automatic initialization and post-commit maintenance in a temporary Git repository, then remove that temporary data. - -## Validation and Acceptance - -The existing test suite and Python compilation must pass. New tests must prove existing dependency reuse, missing dependency installation, checksum rejection, managed global configuration, initialization before MCP startup, hook installation for new and existing indexes, project opt-out, and marker-preserving hook removal. - -Acceptance requires a fresh Codex process to complete a RepoWise tool call without cancellation. A temporary repository must gain `.repowise` and the RepoWise post-commit marker automatically. After a later commit, RepoWise state or its update log must show that the hook targeted the new commit. Unrelated post-commit content must remain before and after removal. - -## Idempotence and Recovery - -Installation, setup, hook installation, and removal are repeatable. Each operation makes one attempt and stops on failure. The task does not add retries, rollback, corrupt-index repair, submodule handling, or custom concurrency control. RepoWise owns concurrency inside its background updater. - -## Artifacts and Notes - -Detailed command results belong in `.agent/test-results/cpk-011-repowise-bootstrap.md`, which is ignored by Git. Do not stage it. - -## Interfaces and Dependencies - -The public commands remain `install`, `setup-repo`, `remove-repo`, `repowise-update`, and `doctor`. Core installation now enables RepoWise globally. `remove-repo` becomes the per-repository opt-out. The implementation uses only Python's standard library, Git, POSIX `sh`, pinned uv 0.12.4, and pinned RepoWise 0.41.0. - -Revision note: Created from the accepted Plan Mode result and revised to require RepoWise's post-commit wiki updater. diff --git a/docs/plans/cpk-012-review-closure.md b/docs/plans/cpk-012-review-closure.md deleted file mode 100644 index 41c1a1b..0000000 --- a/docs/plans/cpk-012-review-closure.md +++ /dev/null @@ -1,89 +0,0 @@ -# Prevent self-invalidating review closure - -This ExecPlan is a living document. Maintain it according to `.agent/PLANS.md`. - -## Purpose / Big Picture - -After this change, a clean review remains valid when the coordinator records only its result and updates matching integrity metadata. A change to code, tests, runtime configuration, requirements, or the supported model still requires a fresh review. - -## Progress - -- [x] (2026-08-14 01:59Z) Reproduced the circular policy and accepted CPK-012. -- [x] (2026-08-14 01:59Z) Activated CPK-012 and merged Design Preflight into this ExecPlan. -- [x] (2026-08-14 02:00Z) Reconciled the distributed review, documentation, roadmap, and ExecPlan rules. -- [x] (2026-08-14 02:00Z) Added one focused policy-consistency check. -- [x] (2026-08-14 02:00Z) Completed validation and prepared the documentation-complete review candidate. -- [x] (2026-08-14 02:02Z) Completed fresh review pass 1 and applied review closure. - -## Surprises & Discoveries - -- Observation: The repository excludes plans, documentation, generated files, and review artifacts from meaningful code changes. - Evidence: The repository instructions require review only for executable source, migrations, dependencies, and runtime, build, or security configuration. -- Observation: The installed skills override that boundary with a rule that invalidates review after any candidate file changes. - Evidence: `assets/skills/docs-maintainer/SKILL.md` says that any candidate file change invalidates a clean review. -- Observation: The roadmap rules require a terminal state both before review and only after review completes. - Evidence: Roadmap finalization precedes review, while the publication gate defines pre-commit review as delivery work that must complete before the terminal transition. - -## Decision Log - -- Decision: Define a small, explicit review-closure class. - Rationale: Status and integrity metadata do not change the behavior or requirements that the reviewer evaluated. - Date/Author: 2026-08-14 / Codex and user -- Decision: Keep automatic classification out of the toolkit. - Rationale: A clear policy and one consistency check solve the current defect without a new commit framework. - Date/Author: 2026-08-14 / Codex -- Decision: Keep version 0.5.0. - Rationale: The current feature candidate is not committed or released. - Date/Author: 2026-08-14 / Codex - -## Outcomes & Retrospective - -The toolkit now has one consistent material-change boundary and one fixed review-closure list. The focused check and complete 24-test suite pass. Fresh correctness review pass 1 was clean. Review closure records that result without starting a recursive review. - -## Context and Orientation - -`assets/AGENTS.block.md` contains the distributed agent rules. The skills under `assets/skills/` own review, documentation, and roadmap procedures. `.agent/PLANS.md` owns ExecPlan procedure. `docs/REVIEW.md` and `docs/OPERATING-MANUAL.md` explain the workflow to users. `tests/test_kit.py` contains policy propagation checks. - -A review-invalidating change can alter behavior, test expectations, requirements, or the supported operating model. A review-closure change records the result of a completed review without changing what the reviewer evaluated. - -## Plan of Work - -Replace the blanket post-review freeze with one shared rule. Code, tests, dependencies, migrations, runtime configuration, security configuration, behavior requirements, and supported-model rules invalidate review. The only permitted review-closure changes are the review result in the active ExecPlan, the same task's roadmap terminal transition, publication status, integrity checksums caused by those updates, and the untracked test-result record. - -Before review, finish code, tests, behavior documentation, and supported-model rules. Keep the roadmap task Active and mark it ready for review. After a clean review, apply only review-closure changes and commit without another review. If review finds a defect, return the task to implementation and review the corrected candidate with fresh context. - -Add one focused consistency check in `tests/test_kit.py`. It must require the closure rule in each policy owner and reject the old blanket invalidation sentence. Update the user documentation only where its current sequence becomes wrong. - -## Concrete Steps - -Work from `/home/mbeutler/Projects/codex-practical-kit`. - -Run: - - ./run-tests.sh - python3 -m py_compile kit.py tests/test_kit.py - sh -n doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh - git diff --check - sha256sum --check MANIFEST.sha256 - -Then run one fresh read-only adversarial review. After a clean result, update only the CPK-012 review status, roadmap terminal state, and checksum manifest. - -## Validation and Acceptance - -The focused check must prove that all distributed policy owners allow review closure without another review. It must also prove that material changes still invalidate review. The existing test suite and lint checks must pass. - -Acceptance has three scenarios. First, a review-result checkbox, terminal roadmap move, and matching checksum update do not require another review. Second, a code, test, configuration, requirement, or supported-model change requires a fresh review. Third, a defect correction follows the existing fresh-pass loop. - -## Idempotence and Recovery - -Policy installation and checks remain repeatable. If an operation fails, stop and report the error. This task does not add retries, rollback, recovery state, or automatic diff classification. - -## Artifacts and Notes - -Record detailed command results in `.agent/test-results/cpk-012-review-closure.md`. This ignored file is not part of the candidate. - -## Interfaces and Dependencies - -No public command or runtime dependency changes. The public workflow gains one term: review closure. It means the fixed set of status and integrity updates permitted after a clean review. - -Revision note: Created from the accepted failure analysis and implementation plan. diff --git a/docs/plans/cpk-013-empty-project-bootstrap.md b/docs/plans/cpk-013-empty-project-bootstrap.md deleted file mode 100644 index 6dc8968..0000000 --- a/docs/plans/cpk-013-empty-project-bootstrap.md +++ /dev/null @@ -1,109 +0,0 @@ -# Bootstrap empty project folders - -This ExecPlan is a living document. Maintain it according to `.agent/PLANS.md`. - -## Purpose / Big Picture - -After this change, a user can create an empty project folder and start Codex in it. The RepoWise MCP startup command initializes Git, builds the RepoWise index, and installs the post-commit hook. Codex does not initialize Git when a non-Git folder contains any entry. - -## Progress - -- [x] (2026-08-14 10:51Z) Reproduced the empty-folder startup path and identified the Git lookup fallback. -- [x] (2026-08-14 10:51Z) Accepted automatic Git initialization for empty folders only. -- [x] (2026-08-14 10:51Z) Created `cpk-013-empty-project-bootstrap`, activated CPK-013, and completed Design Preflight. -- [x] (2026-08-14 10:53Z) Added the empty-folder bootstrap branch and its focused check. -- [x] (2026-08-14 10:53Z) Updated version owners and RepoWise documentation. -- [x] (2026-08-14 10:53Z) Completed validation, documentation maintenance, and the review-ready roadmap update. -- [x] (2026-08-14 10:56Z) Completed a clean adversarial review on pass 1 and recorded review closure. - -## Surprises & Discoveries - -- Observation: RepoWise itself starts in a non-Git folder, but it creates only an empty database instead of a usable project index. - Evidence: The startup log for `/home/mbeutler/Projects/techconnect` reported no `.repowise` directory, then the MCP handshake succeeded. -- Observation: The `codex_apps` server did not reproduce a failure. - Evidence: The startup log and a live restart showed successful initialization. -- Observation: The official OpenAI documentation search returned no accessible MCP startup page in this session. - Evidence: The official-domain search and direct page request returned no page content. - -## Decision Log - -- Decision: Run `git init` only when Git lookup fails and the current folder contains no entries. - Rationale: The user starts Codex in empty folders to create projects, but also uses Codex in non-project folders that must stay unchanged. - Date/Author: 2026-08-14 / user and Codex -- Decision: Treat hidden entries as content. - Rationale: A folder with any entry is not completely empty. - Date/Author: 2026-08-14 / Codex -- Decision: Use version `0.9.1`. - Rationale: CPK-013 corrects the RepoWise bootstrap behavior in the current feature line. - Date/Author: 2026-08-14 / Codex - -## Outcomes & Retrospective - -CPK-013 is complete. Empty non-Git folders now enter the existing Git and RepoWise setup path. Non-empty non-Git folders remain unchanged. All 29 tests pass. Python compilation, shell syntax checks, diff checks, and manifest checks pass. Adversarial review pass 1 found no defects. Publication is not authorized; the branch remains local. - -## Context and Orientation - -The task uses branch `cpk-013-empty-project-bootstrap`. Its base branch is `main`, and its base commit is `e266ded5ca894df2f460ce93e9799f1c2a61e17d`. The isolation form is a normal branch in the existing checkout. The target toolkit version is `0.9.1`. - -`kit.py` owns the global RepoWise MCP command. Its `repowise_bootstrap()` function first asks Git for the repository root. Current code starts a generic RepoWise MCP server when that lookup fails. Therefore, it never reaches the existing index and hook setup path in a new empty folder. - -`tests/test_kit.py` executes the generated shell command with a fake RepoWise executable. `README.md` and `docs/REPOWISE.md` own the user-visible startup behavior. `CODEX-INSTALL-PROMPT.md` and `kit.py` own the current version statements. - -The supported model has one personal user and one Codex writer on a normal local filesystem. The current directory is the Codex workspace. Git and the pinned RepoWise command are installed. A completely empty folder has no visible or hidden entries. - -## Normal-Use Behavior Floor - -If the current directory is already in a Git repository, preserve the current behavior. Initialize RepoWise when its index is absent, install the hook, and start the MCP server for the repository root. - -If the current directory is not in Git and is completely empty, run `git init` once. Then use the same repository bootstrap path. - -If the current directory is not in Git and contains any entry, do not initialize Git, RepoWise, or a hook. Start the generic RepoWise MCP server without a project root. - -If one command fails, stop and report the error. Do not add retry or recovery behavior. - -## Scope Ceiling - -Do not infer workspace trust. Codex owns trust. Do not initialize Git in a non-empty folder. Do not inspect parent intent, add an allowlist, change `codex_apps`, change RepoWise, add dependencies, or add recovery behavior. Do not repair folders changed by an earlier startup. - -## Plan of Work - -Change `repowise_bootstrap()` in `kit.py`. When Git root lookup fails, use `ls -A` to test whether the current directory has one entry. Run quiet `git init` only when the result is empty. Then resolve the new Git root and continue through the existing RepoWise initialization and hook commands. - -Add one focused test in `tests/test_kit.py`. Prove that an empty non-Git folder gains `.git` and uses the full RepoWise path. Prove that a non-empty non-Git folder does not gain `.git` and uses only the generic MCP command. - -Update the existing RepoWise sections in `README.md` and `docs/REPOWISE.md`. Update the toolkit version owners and checksum manifest after all content is final. - -## Concrete Steps - -Work from `/home/mbeutler/Projects/codex-practical-kit` on `cpk-013-empty-project-bootstrap`. - -Run: - - python3 -m unittest tests.test_kit.RepoWiseRuntimeTests.test_bootstrap_initializes_only_empty_non_git_directory - ./run-tests.sh - python3 -m py_compile kit.py tests/test_kit.py assets/hooks/session_start.py - sh -n doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh - git diff --check - sha256sum --check MANIFEST.sha256 - -Record detailed results in `.agent/test-results/cpk-013-empty-project-bootstrap.md`. Keep CPK-013 Active and mark validation complete with review pending. Finalize documentation before one fresh read-only adversarial review. - -## Validation and Acceptance - -The focused check must fail if an empty non-Git folder does not gain `.git`, if RepoWise does not initialize, or if the hook does not install. It must fail if a non-empty non-Git folder gains `.git` or runs RepoWise initialization. - -The full suite must pass. Python compilation, shell syntax, diff, and manifest checks must pass. - -## Idempotence and Recovery - -After `git init`, later MCP starts use the existing Git repository path. RepoWise initialization remains conditional on `.repowise`. If a command fails, stop and report it. Do not retry or repair partial state. - -## Artifacts and Notes - -Preserve the existing untracked `.claude/`, `.codex/`, `.mcp.json`, `.repowise/`, `.vscode/`, and root `AGENTS.md` paths in this toolkit checkout. The diagnostic folder `/home/mbeutler/Projects/techconnect` already contains a RepoWise database from the reported startup and is outside this implementation scope. - -## Interfaces and Dependencies - -No new public command or dependency is required. The generated POSIX shell command continues to use Git, RepoWise, and standard `ls`. The toolkit version becomes `0.9.1`. - -Revision note: Created from the accepted empty-folder rule and Design Preflight. Updated after implementation, validation, documentation maintenance, and clean review closure. diff --git a/docs/plans/cpk-014-stop-doc-commit.md b/docs/plans/cpk-014-stop-doc-commit.md deleted file mode 100644 index e360ede..0000000 --- a/docs/plans/cpk-014-stop-doc-commit.md +++ /dev/null @@ -1,121 +0,0 @@ -# Remove the Stop hook - -This ExecPlan is a living document. Maintain it according to the toolkit-managed `$CODEX_HOME/PLANS.md`. - -## Purpose / Big Picture - -After this change, Codex can stop without a toolkit command that checks review and documentation markers. The installed agent instructions remain the review authority. A fresh install adds only the Session Start hook. A reinstall removes old toolkit-owned Stop and Session End hooks. - -## Progress - -- [x] (2026-08-14 12:58Z) Reproduced the original documentation-commit problem and started CPK-014. -- [x] (2026-08-14 13:03Z) Stopped the commit-classification approach after three defectful review passes. -- [x] (2026-08-14 13:03Z) Accepted the user decision to remove Stop gating and completed a new Design Preflight. -- [x] (2026-08-14 15:11Z) Removed Stop-hook installation, state management, scripts, and tests. -- [x] (2026-08-14 15:11Z) Added one focused reinstall check that preserves unrelated hooks. -- [x] (2026-08-14 15:11Z) Updated version owners and user documentation. -- [x] (2026-08-14 15:11Z) Corrected the compiled-hook cleanup defect from removal review pass 1. -- [x] (2026-08-14 15:11Z) Completed fresh removal review pass 2. The review was clean after the pass-1 correction. Applied review closure. - -## Surprises & Discoveries - -- Observation: Commit classification expanded from one reported documentation case into Git-history policy. - Evidence: Three review passes found distinct defects in baseline status, merge diffs, and divergent branches. -- Observation: Session End exists only to erase state that the Stop hook uses. - Evidence: `assets/hooks/session_end.py` calls only `remove_baseline()`. -- Observation: The documented test command can create compiled hook files before installation. - Evidence: Removal review pass 1 found that recursive copy preserved obsolete files under `assets/hooks/__pycache__`. - -## Decision Log - -- Decision: Remove the toolkit-owned Stop and Session End hooks. - Rationale: The installed agent instructions already require review. The user monitors missed reviews and rejected more Stop-hook complexity. - Date/Author: 2026-08-14 / user -- Decision: Preserve old hook names as uninstall identifiers. - Rationale: Reinstallation must remove toolkit-owned entries from earlier versions without changing unrelated hooks. - Date/Author: 2026-08-14 / Codex -- Decision: Use version `0.10.0`. - Rationale: Removing an installed hook is a breaking change before version 1.0.0. - Date/Author: 2026-08-14 / Codex - -## Outcomes & Retrospective - -CPK-014 is complete. The toolkit installs only Session Start. Reinstallation replaces the hook directory and preserves unrelated configured handlers. Removal review pass 1 found one compiled-file cleanup defect. The correction is complete. All 25 tests pass. Python compilation, Session Start JSON, shell syntax, diff, and manifest checks pass. Fresh removal review pass 2 was clean after fixes. Publication is authorized. PR mode is off, so the reviewed branch will be pushed without a pull request or merge. - -## Context and Orientation - -The task uses branch `cpk-014-stop-doc-commit`. Its base branch is `main`, and its base commit is `3546f98923dd9784b5a512456a17088c9867d0e2`. The isolation form is a normal branch in the existing checkout. The target toolkit version is `0.10.0`. - -`kit.py` copies hook scripts into the toolkit install directory and manages entries in `$CODEX_HOME/hooks.json`. `HOOK_HANDLER_BASENAMES` identifies toolkit-owned handlers from current and old versions. `install_hooks()` removes those entries before it adds current handlers. - -`assets/hooks/session_start.py` injects the compact working agreement. It also saves Git state for `assets/hooks/stop_gate.py`. `assets/hooks/session_end.py` removes that state. If Stop gating is removed, the saved state and Session End cleanup have no remaining reader. - -`tests/test_kit.py` contains direct Stop-hook behavior tests. It also contains installer tests that can prove upgrade cleanup and preservation of unrelated configuration. - -The supported model has one personal user and one Codex writer on a normal local filesystem. Agent instructions require review for code and configuration changes. The user observes the agent workflow. - -## Normal-Use Behavior Floor - -A fresh install adds the toolkit-owned Session Start hook. It does not add a Stop or Session End hook. - -A reinstall removes old toolkit handler entries and obsolete hook files. It preserves unrelated handlers in the same hook events. - -Session Start continues to inject the compact working agreement. It does not create per-session Git state. - -The doctor command passes only when Session Start is installed and obsolete toolkit hooks are absent. - -## Scope Ceiling - -Do not weaken or remove review rules from agent instructions, skills, ExecPlan rules, or documentation. Do not add a replacement reminder, a configuration switch, telemetry, or persistent state. Do not change RepoWise or its separate Git `post-commit` hook. Do not change unrelated user hook entries. - -## Plan of Work - -In `kit.py`, keep all old toolkit hook names for ownership detection. Install only `session_start.py`. Remove obsolete scripts from an existing install directory. Make the doctor reject obsolete toolkit handlers. - -Make `assets/hooks/session_start.py` emit its fixed context without shared state helpers. Delete `assets/hooks/hook_common.py`, `assets/hooks/stop_gate.py`, and `assets/hooks/session_end.py`. - -Delete direct Stop behavior tests from `tests/test_kit.py`. Add one installer test that begins with toolkit-owned old hooks and an unrelated Stop handler. Reinstall the toolkit. Prove that only the unrelated Stop handler and the current Session Start handler remain. Prove that obsolete script files are absent. - -Remove current Stop-hook behavior from `README.md` and `docs/OPERATING-MANUAL.md`. Keep historical version documents unchanged. Update the installation prompt and version owners to `0.10.0`. Regenerate `MANIFEST.sha256` after all tracked content is final. - -## Concrete Steps - -Work from `/home/mbeutler/Projects/codex-practical-kit` on `cpk-014-stop-doc-commit`. - -Run: - - python3 -m unittest tests.test_kit.InstallerTests.test_reinstall_removes_stop_hooks - ./run-tests.sh - sh -n doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh - git diff --check - sha256sum --check MANIFEST.sha256 - -Record current results in `.agent/test-results/cpk-014-stop-doc-commit.md`. Keep CPK-014 Active and mark validation complete with review pending. Finalize documentation before one fresh read-only adversarial review. - -## Validation and Acceptance - -The focused check must fail if installation adds a Stop or Session End hook. It must fail if reinstallation keeps an obsolete toolkit handler or removes an unrelated handler. - -The full suite must pass. Python compilation, shell syntax, diff, and manifest checks must pass. - -## Idempotence and Recovery - -Installation removes owned hook entries before it adds Session Start. Repeated installation gives the same managed hook configuration. If an operation fails, stop and report it. Do not retry or repair state. - -## Artifacts and Notes - -Preserve the existing untracked `.mcp.json`, `.repowise/`, and `.vscode/` paths. Do not stage `.agent/test-results/`. - -## Interfaces and Dependencies - -No new dependency or public command is required. `$CODEX_HOME/hooks.json` keeps the current Codex hook format. The toolkit installs only `assets/hooks/session_start.py`. - -Revision note: Replaced the stopped commit-classification design after the user chose to remove Stop gating. - -Revision note: Updated after implementation, validation, documentation maintenance, and the ready-for-review roadmap transition. - -Revision note: Updated after removal review pass 1 to replace the installed hook directory with one Session Start file. - -Revision note: Updated after clean removal review pass 2 to record review closure and publication status. - -Revision note: Updated before commit to record authorized direct branch publication with PR mode off. diff --git a/docs/plans/cpk-015-config-toml-hooks.md b/docs/plans/cpk-015-config-toml-hooks.md deleted file mode 100644 index dfedb74..0000000 --- a/docs/plans/cpk-015-config-toml-hooks.md +++ /dev/null @@ -1,141 +0,0 @@ -# Install Codex hooks in config.toml - -This ExecPlan is a living document. Maintain it according to the repository's `.agent/PLANS.md`. - -## Purpose / Big Picture - -After this change, the installer records the toolkit Session Start hook in `$CODEX_HOME/config.toml`, which is the documented Codex configuration file. Repeated installation preserves unrelated TOML configuration and does not create the legacy `$CODEX_HOME/hooks.json` file. - -## Progress - -- [x] (2026-08-14 15:39Z) Inspected the installer path, the current converted configuration, and the official Codex configuration reference. -- [x] (2026-08-14 15:39Z) Defined the normal-use behavior floor and scope ceiling. -- [x] (2026-08-14 15:39Z) Activated CPK-015 on an isolated task branch. -- [x] (2026-08-14 15:48Z) Replaced legacy JSON hook management with a marker-delimited TOML block. -- [x] (2026-08-14 15:48Z) Updated the focused installer test and affected install documentation. -- [x] (2026-08-14 15:48Z) Passed all 25 initial tests, Python compilation, shell syntax, diff, and manifest checks. -- [x] (2026-08-14 16:01Z) Corrected the sibling-handler preservation defect from review pass 1 and passed all 26 tests. -- [x] (2026-08-14 16:10Z) Corrected the inline-comment boundary defect from review pass 2 and passed all 26 tests. -- [x] (2026-08-14 16:31Z) Applied the user direction to delete text-boundary adoption and use parsed hook-entry existence only. -- [x] (2026-08-14 16:31Z) Passed the focused existing-hook checks and all 25 tests after simplification. -- [x] (2026-08-14 16:42Z) Corrected the pre-existing-file rewrite found in fresh review pass 1 and passed all 25 tests. -- [x] (2026-08-14 16:50Z) Completed fresh review pass 2. The candidate is clean after the pass-1 correction. Applied review closure. - -## Surprises & Discoveries - -- Observation: The installer calls the legacy file `hooks.json`, although the report called it `config.json`. - Evidence: `load_hooks_config()`, `install_hooks()`, `uninstall_hooks()`, and `doctor()` in `kit.py` read `$CODEX_HOME/hooks.json`. -- Observation: The current converted environment already contains the accepted Session Start TOML shape. - Evidence: `$CODEX_HOME/config.toml` uses `[[hooks.SessionStart]]` and `[[hooks.SessionStart.hooks]]` with the current command fields. -- Observation: An exact handler can be the first handler in a Session Start group that also contains an unrelated handler. - Evidence: Review pass 1 showed that a marker around only the matching prefix makes uninstall change the remaining handler's parent table. -- Observation: A valid TOML array-table header can have an inline comment. - Evidence: Review pass 2 showed that a bare-string comparison missed `[[hooks.SessionStart.hooks]] # user hook`. -- Observation: TOML quoted keys and whitespace around dots can name the same array table. - Evidence: Review pass 3 showed that `[[hooks."SessionStart".hooks]]` bypasses the canonical-header expression and can orphan an unrelated handler during uninstall. -- Observation: `remove_marker_block()` normalizes whitespace even when its marker is absent. - Evidence: Fresh review pass 1 showed that hook uninstall could rewrite a pre-existing file without owning a hook block. - -## Decision Log - -- Decision: Manage one marker-delimited Session Start block in `$CODEX_HOME/config.toml`. - Rationale: `kit.py` already uses marker blocks to preserve unrelated TOML when it installs RepoWise configuration. - Date/Author: 2026-08-14 / Codex -- Decision: Adopt an exact unmarked copy of the current Session Start block on first installation. - Rationale: Superseded. Textual adoption created false ownership of neighboring TOML content. - Date/Author: 2026-08-14 / Codex -- Decision: Do not migrate arbitrary legacy JSON hook entries. - Rationale: The task only changes the install procedure, and the current environment needs no migration. Unrelated user configuration remains outside toolkit ownership. - Date/Author: 2026-08-14 / Codex -- Decision: Keep version `0.10.0`. - Rationale: Version `0.10.0` is an untagged release candidate. This correction fixes its Session Start installation procedure before release. - Date/Author: 2026-08-14 / Codex -- Decision: Stop automatic correction and publication after review pass 3. - Rationale: The repository breaker forbids another automatic fix after three consecutive defectful passes. - Date/Author: 2026-08-14 / Codex -- Decision: Parse `config.toml` and check only for the expected nested Session Start handler values. - Rationale: The user rejected textual table-boundary logic. Existing matching entries remain unchanged. Absent entries get one managed block. - Date/Author: 2026-08-14 / user and Codex -- Decision: Drop the fresh review pass 2 whitespace-only finding. - Rationale: Blank-line normalization does not change a TOML entry or behavior. It does not violate the user's explicit entry-based requirement. - Date/Author: 2026-08-14 / Codex - -## Outcomes & Retrospective - -CPK-015 is complete. The installer parses `config.toml` with the Python standard library. If the expected nested Session Start handler exists, installation leaves it unchanged. If it is absent, installation appends one managed block. Uninstall returns without writing when that marker is absent. Quoting, comments, table order, whitespace, and unrelated configuration do not affect the existence check. All 25 tests pass. Fresh review pass 2 was clean after the pass-1 correction. Direct branch publication is authorized because PR mode is off. - -## Context and Orientation - -The task uses branch `cpk-015-config-toml-hooks`. Its base branch is `cpk-014-stop-doc-commit`, and its base commit is `7be10c6de3b47b88c6bae6d57942d859ac8aa61a`. This stacked branch is necessary because CPK-014 is pushed but is not yet integrated into `main`. The isolation form is a normal branch in the existing checkout. The target toolkit version remains `0.10.0`. - -`kit.py` owns installation, removal, and diagnosis. Its hook functions read `$CODEX_HOME/config.toml` with the standard library `tomllib` parser. The file also has `marker_block()` and `remove_marker_block()` helpers for blocks that the installer creates. - -`tests/test_kit.py` has a focused reinstall test. It proves that an existing matching handler remains unchanged, including when TOML uses quoted keys. It also proves idempotence and the absence of a new JSON file. - -`README.md` and `CODEX-INSTALL-PROMPT.md` name the legacy hook file. These statements must name `config.toml` after the behavior changes. - -The supported operating model has one personal user and one Codex writer on a normal local filesystem. The installer owns only its marker-delimited TOML block and its installed hook script. On failure, it stops and reports the error. - -## Normal-Use Behavior Floor - -A fresh install adds one Session Start hook block to `$CODEX_HOME/config.toml`. A repeated install produces the same managed block. If the expected nested handler already exists, installation leaves it unchanged. Unrelated TOML content remains unchanged. Installation does not create `$CODEX_HOME/hooks.json`. - -Uninstall removes only a toolkit marker block that installation created. It does not remove a matching pre-existing handler. Doctor passes when the expected handler values and installed script are present. - -## Scope Ceiling - -Do not edit the live `$CODEX_HOME/config.toml`. Do not migrate arbitrary JSON handlers. Do not manage unrelated Codex hooks or the RepoWise Git `post-commit` hook. Do not add a TOML writing dependency, a general parser, recovery behavior, or compatibility configuration. - -## Plan of Work - -In `kit.py`, parse `config.toml` with `tomllib`. Check the nested Session Start handler values without inspecting text boundaries. If the handler is absent, append the managed block. On uninstall, remove only that marker block. Update doctor and command output to inspect `config.toml`. - -In `tests/test_kit.py`, use a TOML file with unrelated configuration and an existing matching handler under quoted keys. Install twice and prove that no duplicate or marker appears. Uninstall and prove that the pre-existing handler remains. For a fresh configuration, prove that install and uninstall add and remove only the managed block. - -Update only the affected install instructions. Regenerate `MANIFEST.sha256` after all tracked content is final. - -## Concrete Steps - -Work from `/home/mbeutler/Projects/codex-practical-kit` on `cpk-015-config-toml-hooks`. - -Run: - - python3 -m unittest tests.test_kit.InstallerTests.test_reinstall_accepts_existing_config_toml_hook - ./run-tests.sh - sh -n doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh - git diff --check - sha256sum --check MANIFEST.sha256 - -Record current commands, exit status, and concise evidence in the untracked `.agent/test-results/cpk-015-config-toml-hooks.md` file. Before review, mark validation complete and review pending. - -## Validation and Acceptance - -The focused test must fail if installation creates `hooks.json`, duplicates the existing Session Start hook, or removes pre-existing TOML. The fresh-install test must fail if uninstall leaves its managed block. The full test suite, Python compilation, shell syntax, diff, and manifest checks must pass. - -## Idempotence and Recovery - -Installation is repeatable when the handler is pre-existing or managed. Uninstall removes only the managed marker block. If an operation fails, stop and report it. Do not retry, roll back, or repair unrelated configuration. - -## Artifacts and Notes - -Preserve the existing untracked `.mcp.json`, `.repowise/`, and `.vscode/` paths. Never stage `.agent/test-results/`. - -## Interfaces and Dependencies - -No new dependency or public command is required. `kit.py` continues to use Python's standard library. The installed TOML interface is one `[[hooks.SessionStart]]` table with one nested `[[hooks.SessionStart.hooks]]` command table. - -Revision note: Created after repository inspection and Design Preflight to record the accepted CPK-015 implementation. - -Revision note: Updated after implementation, documentation maintenance, validation, and the ready-for-review roadmap transition. - -Revision note: Updated after review pass 1 to record the sibling-handler correction and fresh validation. - -Revision note: Updated after review pass 2 to record the inline-comment correction and fresh validation. - -Revision note: Updated after review pass 3 to record the validated blocker and stop publication. - -Revision note: Replaced textual adoption with the user-directed parsed existence check. The resumed task now awaits fresh review. - -Revision note: Updated after fresh review pass 1 to record the no-marker uninstall guard and byte-preservation check. - -Revision note: Updated after fresh review pass 2 to record the rejected whitespace-only finding, clean review closure, and authorized publication. diff --git a/docs/plans/cpk-016-required-repowise.md b/docs/plans/cpk-016-required-repowise.md deleted file mode 100644 index 93b01a5..0000000 --- a/docs/plans/cpk-016-required-repowise.md +++ /dev/null @@ -1,111 +0,0 @@ -# Require the RepoWise code graph - -This ExecPlan is a living document. Maintain it according to the repository's `.agent/PLANS.md`. - -## Purpose / Big Picture - -After this change, Codex waits for RepoWise to initialize before a session starts. The first session in an unindexed Git repository no longer continues without the code graph. Toolkit instructions treat RepoWise as required repository knowledge, not an optional provider. - -## Progress - -- [x] (2026-08-14 16:32Z) Reproduced the first-start timing and confirmed that RepoWise completed after Codex omitted the pending optional server. -- [x] (2026-08-14 16:32Z) Verified the official Codex `required` and `startup_timeout_sec` MCP settings. -- [x] (2026-08-14 16:32Z) Defined the behavior floor, scope ceiling, and target version. -- [x] (2026-08-14 16:32Z) Activated CPK-016 on an isolated task branch. -- [x] (2026-08-14 16:58Z) Added required RepoWise startup and removed optional-provider guidance. -- [x] (2026-08-14 16:58Z) Updated focused tests, documentation, and version owners. -- [x] (2026-08-14 16:58Z) Passed 26 tests, Python compilation, shell syntax checks, and the diff check. -- [x] (2026-08-14 17:16Z) Updated checksums and completed clean-context review after two fixes on pass 3. - -## Surprises & Discoveries - -- Observation: Automatic initialization succeeded even though Codex displayed an MCP startup warning. - Evidence: Codex omitted a pending optional server at 12:24:45. RepoWise finished 24.9 seconds later and completed the MCP handshake at 12:25:12. -- Observation: The managed table already gives RepoWise a 1,800-second startup timeout. - Evidence: `repowise_config_block()` writes `startup_timeout_sec = 1800`, but it does not write `required = true`. -- Observation: Review pass 1 found fallback guidance in `docs/OPTIONAL-REVIEW-TOOLS.md`. - Evidence: The guide told users to continue with native tools when RepoWise failed. The candidate now uses the required stop-and-restore policy. -- Observation: Review pass 2 found an optional RepoWise heading in the bundled review packet. - Evidence: The packet now labels the section `RepoWise observations`, and the policy test covers the file. - -## Decision Log - -- Decision: Set `required = true` in the managed RepoWise MCP table. - Rationale: Official Codex configuration defines this flag as the startup and resume gate for an enabled MCP server. The existing timeout bounds the wait. - Date/Author: 2026-08-14 / user and Codex -- Decision: Remove fallback guidance from toolkit-owned agent instructions and current documentation. - Rationale: The user made the code graph a mandatory toolkit component. Continuing without it contradicts that requirement. - Date/Author: 2026-08-14 / user and Codex -- Decision: Use version `0.11.0`. - Rationale: Required RepoWise startup is a breaking behavior change before version 1.0.0. - Date/Author: 2026-08-14 / Codex - -## Outcomes & Retrospective - -Version 0.11.0 makes RepoWise a required MCP server and keeps the 1,800-second startup bound. Toolkit guidance now stops when the graph is unavailable. All 26 tests and required checks pass. Review pass 3 is clean after two consistency fixes. - -Publication status: A local checkpoint commit is authorized. Push is not authorized for CPK-016. - -## Context and Orientation - -The task uses branch `cpk-016-required-repowise`. Its base branch is `cpk-015-config-toml-hooks`, and its base commit is `2bd33d71f886a759ef2ebf667c6b960498bfd9c9`. This stacked branch is necessary because CPK-015 is published but is not integrated into `main`. The isolation form is a normal branch in the existing checkout. The target version is `0.11.0`. - -`kit.py` renders the global RepoWise MCP table in `repowise_config_block()`. Its bootstrap command initializes an absent index before it starts the MCP server. The table already sets `startup_timeout_sec = 1800`. - -Codex treats an MCP server as optional unless its table sets `required = true`. The official configuration reference says that a required enabled server gates startup and resume. The timeout controls how long Codex waits for initialization. - -`assets/AGENTS.block.md`, `assets/hooks/session_start.py`, and `kit.py:repowise_agents_block()` currently tell agents to fall back when RepoWise is unavailable. `README.md`, `docs/REPOWISE.md`, and `docs/WHY-THIS-SHAPE.md` repeat that optional model. - -The supported operating model has one personal user and one Codex writer on a normal local filesystem. RepoWise 0.41.0 is installed by the toolkit. The automatic bootstrap owns index creation and Git-hook installation. - -## Normal-Use Behavior Floor - -The managed global MCP table contains `required = true` and `startup_timeout_sec = 1800`. Codex waits for first-time index creation and MCP initialization before it starts or resumes a session. If initialization fails or exceeds the timeout, Codex startup fails instead of continuing without the graph. - -Toolkit-owned instructions require current RepoWise knowledge before broad repository exploration. If the index is stale, the agent refreshes it. Source remains the correctness authority. - -## Scope Ceiling - -Do not redesign the bootstrap command, add polling, add retry or recovery, change RepoWise, or change Codex. Do not make generated RepoWise prose mandatory. Do not remove direct source verification. Do not change repository opt-out commands in this task. - -## Plan of Work - -Add `required = true` to `repowise_config_block()` next to the existing startup timeout. Update doctor to require the flag. Add a focused assertion to the existing install test. - -Replace optional-provider wording in the current toolkit-owned agent instructions and documentation. State that a stale index must be refreshed and that source remains authoritative. Update version owners to `0.11.0`. - -Regenerate `MANIFEST.sha256` after code and documentation are final. - -## Concrete Steps - -Work from `/home/mbeutler/Projects/codex-practical-kit` on `cpk-016-required-repowise`. - -Run: - - python3 -m unittest tests.test_kit.InstallerTests.test_install_preserves_global_config_and_uninstall_removes_owned_block - ./run-tests.sh - sh -n doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh - git diff --check - sha256sum --check MANIFEST.sha256 - -Record current results in `.agent/test-results/cpk-016-required-repowise.md`. Keep CPK-016 Active and mark validation complete before review. - -## Validation and Acceptance - -The focused install test must fail if the generated global RepoWise table omits `required = true` or the existing timeout. The full suite and compilation must pass. Shell syntax, diff, and manifest checks must pass. - -The candidate must contain no current toolkit instruction that calls RepoWise optional or tells an agent to continue without it. - -## Idempotence and Recovery - -The managed marker block replaces its prior contents on reinstall. Repeated installation produces one required RepoWise table. If initialization fails, Codex applies its configured required-server failure. The toolkit does not retry or recover. - -## Artifacts and Notes - -Preserve the untracked `.mcp.json`, `.repowise/`, and `.vscode/` paths. Never stage `.agent/test-results/`. - -## Interfaces and Dependencies - -No new dependency or command is required. The public configuration change is `mcp_servers.repowise.required = true`. The existing `startup_timeout_sec = 1800` remains the wait bound. - -Revision note: Created after the user made RepoWise mandatory and local logs confirmed the optional-server startup race. diff --git a/docs/plans/cpk-017-review-cycle-accounting.md b/docs/plans/cpk-017-review-cycle-accounting.md deleted file mode 100644 index c9a1eb2..0000000 --- a/docs/plans/cpk-017-review-cycle-accounting.md +++ /dev/null @@ -1,98 +0,0 @@ -# Count only implementation defects toward the review breaker - -This ExecPlan is a living document. Maintain it according to the repository's `.agent/PLANS.md`. - -## Purpose / Big Picture - -After this change, documentation and review-housekeeping findings can be corrected without consuming the three-defect breaker. The breaker counts only consecutive review passes that find validated defects in executable source, tests, migrations, dependencies, or runtime, build, or security configuration. - -## Progress - -- [x] (2026-08-14 17:24Z) Confirmed that the current review skill counts every validated P0, P1, or P2 finding. -- [x] (2026-08-14 17:24Z) Defined the count floor, scope ceiling, and existing review skill as the behavior owner. -- [x] (2026-08-14 17:24Z) Created stacked task branch `cpk-017-review-cycle-accounting` and activated CPK-017. -- [x] (2026-08-14 17:31Z) Corrected the review skill and its installed summaries. -- [x] (2026-08-14 17:31Z) Added one consistency test and updated affected documentation. -- [x] (2026-08-14 17:31Z) Passed the focused test, 27 full-suite tests, compilation, shell syntax, and the diff check. -- [x] (2026-08-14 17:39Z) Validated checksums and completed clean-context review on pass 1. - -## Surprises & Discoveries - -- Observation: The installed agent rules already say to stop when pass 3 finds a code defect, but the detailed review skill counts all validated correctness defects. - Evidence: `assets/AGENTS.block.md` names a code defect. `assets/skills/adversarial-review/SKILL.md` makes every P0, P1, or P2 finding defectful. - -## Decision Log - -- Decision: Documentation and review-housekeeping findings neither increment nor reset the breaker count. - Rationale: They remain valid work, but they are not evidence of repeated implementation failure. - Date/Author: 2026-08-14 / user and Codex -- Decision: Keep the limit at three consecutive counted passes. - Rationale: The user corrected what counts. The user did not change the implementation-defect limit. - Date/Author: 2026-08-14 / Codex -- Decision: Keep version 0.11.0. - Rationale: This policy correction is part of the unpublished 0.11.0 candidate. It does not consume another version. - Date/Author: 2026-08-14 / Codex - -## Outcomes & Retrospective - -The review skill now counts only implementation defects toward the three-defect breaker. Documentation and housekeeping remain actionable without changing the count. The focused policy test and all 27 tests pass. Review pass 1 is clean. - -Publication status: A local checkpoint commit is authorized. Push is not authorized for CPK-017. - -## Context and Orientation - -The task uses branch `cpk-017-review-cycle-accounting`. Its base branch is `cpk-016-required-repowise`, and its base commit is `ebf461f376f1ceead82f4962bf7a4c0d07bae4e7`. This normal stacked branch preserves the reviewed CPK-016 checkpoint. CPK-015 and CPK-016 are not integrated into `main`. - -`assets/skills/adversarial-review/SKILL.md` owns the detailed finding and breaker procedure. `assets/AGENTS.block.md` installs the main agent rules. `README.md`, `docs/REVIEW.md`, `docs/OPERATING-MANUAL.md`, and `docs/WHY-THIS-SHAPE.md` explain the same policy. `tests/test_kit.py` checks that distributed policy owners agree. - -A counted defect is a validated P0, P1, or P2 correctness defect in executable source, tests, migrations, dependencies, or runtime, build, or security configuration. A documentation finding concerns prose or static documentation. Review housekeeping includes plans, roadmap state, publication records, checksums, manifests, staging scope, and ignored test-result records. - -## Normal-Use Behavior Floor - -Every validated in-scope finding remains actionable. Fixing a finding requires validation and a fresh reviewer when the candidate changes. Only a pass with a counted implementation defect advances the three-defect breaker. A documentation-only or housekeeping-only pass does not increment or reset the current count. - -The coordinator stops before another automatic fix when the third consecutive counted pass finds an implementation defect. The four-part supported-model gate remains unchanged. - -## Scope Ceiling - -Do not weaken finding validation, review coverage, clean-review requirements, or documentation maintenance. Do not change the limit from three. Do not add persistent counter state or automation. Do not change version 0.11.0. - -## Plan of Work - -Rewrite the validation and breaker sections in `assets/skills/adversarial-review/SKILL.md` so any validated finding can be fixed, while only implementation defects affect the breaker count. Synchronize the shorter rule in `assets/AGENTS.block.md` and the current explanatory documents. - -Add one integration test in `tests/test_kit.py`. The test must read every current policy owner and require the shared rule that documentation and housekeeping findings do not increment or reset the count. Regenerate `MANIFEST.sha256` after all tracked content is final. - -## Concrete Steps - -Work from `/home/mbeutler/Projects/codex-practical-kit` on `cpk-017-review-cycle-accounting`. - -Run: - - python3 -m unittest tests.test_kit.IntegrationTests.test_review_cycle_counts_only_implementation_defects - ./run-tests.sh - sh -n doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh - git diff --check - sha256sum --check MANIFEST.sha256 - -Record results in `.agent/test-results/cpk-017-review-cycle-accounting.md`. Never stage that file. - -## Validation and Acceptance - -The focused test must fail if a current review-policy owner says that documentation or housekeeping advances or resets the breaker. The full suite, compilation, shell syntax, diff, and manifest checks must pass. - -A human reading the detailed review skill must see that any validated finding remains actionable, that documentation and housekeeping do not change the counter, and that the third consecutive counted implementation-defect pass stops automatic correction. - -## Idempotence and Recovery - -The edits are static policy text and tests. Repeating validation is safe. Stop and report the first command failure. Do not add retry or recovery behavior. - -## Artifacts and Notes - -Preserve `.mcp.json`, `.repowise/`, and `.vscode/`. They are untracked environment state outside this task. - -## Interfaces and Dependencies - -No runtime interface or dependency changes. The policy term `counted implementation defect` is introduced only to distinguish breaker accounting from other actionable findings. - -Revision note: Created after review housekeeping consumed two passes during CPK-016 and the user corrected the intended breaker accounting. diff --git a/docs/plans/cpk-018-compact-agents-profile.md b/docs/plans/cpk-018-compact-agents-profile.md deleted file mode 100644 index 3c19e49..0000000 --- a/docs/plans/cpk-018-compact-agents-profile.md +++ /dev/null @@ -1,114 +0,0 @@ -# Compact the global agent profile - -This ExecPlan is a living document. Maintain it according to the repository's `.agent/PLANS.md`. - -## Purpose / Big Picture - -After this change, the global Codex `AGENTS.md` uses fewer than 100 lines. It keeps the toolkit rules without repeating detailed skill procedures. A subagent can read the file without assuming coordinator authority. - -## Progress - -- [x] (2026-08-14 17:52Z) Measured the live profile at 244 lines and the managed toolkit block at 191 lines. -- [x] (2026-08-14 17:52Z) Confirmed that the installer replaces only the marker-delimited toolkit block and preserves other profile text. -- [x] (2026-08-14 17:52Z) Read the official Codex instruction-discovery guidance and defined the behavior floor and scope ceiling. -- [x] (2026-08-14 17:52Z) Created stacked task branch `cpk-018-compact-agents-profile` and activated CPK-018. -- [x] (2026-08-14 18:04Z) Compressed the managed block to 92 lines and added explicit role boundaries. -- [x] (2026-08-14 18:04Z) Added a focused installation and policy check. -- [x] (2026-08-14 18:04Z) Passed the focused test, 28 full-suite tests, and Python compilation. -- [x] (2026-08-14 18:09Z) Finished documentation, shell checks, diff checks, and checksum validation. -- [x] (2026-08-14 18:18Z) Completed clean-context review after one instruction fix on pass 2. -- [x] (2026-08-14 18:18Z) Authorized the local checkpoint and one-time live profile installation. - -## Surprises & Discoveries - -- Observation: Removing only the unmanaged prefix cannot meet the requested line limit. - Evidence: `/home/mbeutler/.codex/AGENTS.md` has 244 lines. `assets/AGENTS.block.md` has 191 lines. -- Observation: The unmanaged prefix conflicts with toolkit review accounting. - Evidence: It limits all findings to six review cycles. The managed toolkit counts only implementation-defect passes. -- Observation: Review pass 1 found that compaction retained cleanup authorization but removed the integration and clean-state gates. - Evidence: The compact block now requires proven integration, clean state, and separate cleanup authorization. - -## Decision Log - -- Decision: Keep detailed procedures in their existing skills, plans file, and repository documentation. - Rationale: The global profile must select and constrain those owners. It does not need to repeat them. - Date/Author: 2026-08-14 / Codex -- Decision: Label coordinator-only duties and define a strict subagent boundary first. - Rationale: Global instructions apply to every agent. A role boundary prevents a subagent from assuming lifecycle or publication authority. - Date/Author: 2026-08-14 / user and Codex -- Decision: Preserve marker-based installation for arbitrary profiles. - Rationale: This task authorizes removal of conflicting text from the user's current profile. It does not authorize deletion of another user's text. - Date/Author: 2026-08-14 / Codex -- Decision: Keep version 0.11.0. - Rationale: This policy rewrite is part of the unpublished 0.11.0 candidate. - Date/Author: 2026-08-14 / Codex - -## Outcomes & Retrospective - -The managed block is 92 lines. The focused profile test and all 28 tests pass. Review pass 2 is clean after the cleanup-gate fix. The candidate is ready for its local checkpoint and authorized live installation. - -Publication status: A local checkpoint commit is authorized. Push is not authorized for CPK-018. - -## Context and Orientation - -The task uses branch `cpk-018-compact-agents-profile`. Its base branch is `cpk-017-review-cycle-accounting`, and its base commit is `8740dee90f0ea5f6371352791e4e9932dddb2fda`. The branch is stacked because CPK-015 through CPK-017 are not integrated into `main`. - -`assets/AGENTS.block.md` is the managed policy source. `kit.py:install_global_agents()` inserts that source between markers in `$CODEX_HOME/AGENTS.md`. It preserves text outside the markers. `/home/mbeutler/.codex/AGENTS.md` contains 53 unmanaged lines before its 191-line managed block. - -Official Codex documentation says that Codex reads the global file once per run. It then appends repository instructions in path order. Later repository instructions have higher precedence. A shorter global file reduces the instruction content in every session. - -The installed skills own detailed procedures. `adversarial-review` owns review loops. `roadmap-maintainer` owns roadmap lifecycle. `docs-maintainer` owns documentation updates. `design-preflight` owns non-trivial design checks. `.agent/PLANS.md` or `$CODEX_HOME/PLANS.md` owns ExecPlan procedure. - -## Normal-Use Behavior Floor - -The complete live profile has fewer than 100 lines after installation and profile cleanup. The managed block tells agents to use the detailed skills instead of duplicating their procedures. - -Only the active coordinator can delegate, change roadmap lifecycle state, manage branches, commit, publish, or orchestrate review. A subagent performs only its assigned task. It does not delegate, create follow-up work, change lifecycle state, commit, publish, or assume coordinator duties. A read-only reviewer does not edit. - -The compact block retains the supported-model gate, RepoWise requirement, task isolation, validation, review, documentation, version, publication, and cleanup boundaries. - -## Scope Ceiling - -Do not weaken security, validation, review, documentation, Git isolation, publication, version, or cleanup rules. Do not add a new configuration file, dependency, parser, or role system. Do not change marker replacement or erase arbitrary unmanaged profile text during general installation. - -## Plan of Work - -Replace `assets/AGENTS.block.md` with a compact policy index. Put the role boundary first. Label coordinator-only work. Refer to installed skills and plan rules for detailed procedures. - -Update `tests/test_kit.py` with one focused profile test. It must install into a temporary profile, preserve unrelated text, limit the managed result to fewer than 100 lines, and require the subagent restrictions. Update current documentation only if it states a conflicting profile contract. - -After the candidate passes review and is committed, run the installer. Then remove the known conflicting unmanaged prefix from `/home/mbeutler/.codex/AGENTS.md`. Keep the toolkit marker block. Verify the live file line count and role text in a new read. - -## Concrete Steps - -Work from `/home/mbeutler/Projects/codex-practical-kit` on `cpk-018-compact-agents-profile`. - -Run: - - python3 -m unittest tests.test_kit.InstallerTests.test_global_agents_profile_is_compact_and_subagent_safe - ./run-tests.sh - sh -n doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh - git diff --check - sha256sum --check MANIFEST.sha256 - -Record results in `.agent/test-results/cpk-018-compact-agents-profile.md`. Never stage that file. - -## Validation and Acceptance - -The focused test must fail when the installed profile reaches 100 lines. It must fail when a subagent can delegate or assume coordinator duties. The existing policy tests must prove that compaction preserves required behavior. - -After installation and profile cleanup, `wc -l /home/mbeutler/.codex/AGENTS.md` must report fewer than 100 lines. `./doctor.sh` must report a ready installation. - -## Idempotence and Recovery - -Repeated installation replaces one managed block and preserves remaining profile text. The one-time live cleanup removes only the prefix that the user supplied in this session. If an operation fails, stop and report it. - -## Artifacts and Notes - -Preserve `.mcp.json`, `.repowise/`, and `.vscode/`. They are untracked environment state outside this task. - -## Interfaces and Dependencies - -No runtime interface or dependency changes. The public result is the content and maximum line count of the global Codex instruction file. - -Revision note: Created after the user requested a compact, conflict-free, subagent-safe profile. diff --git a/docs/plans/cpk-019-publish-direct-integration.md b/docs/plans/cpk-019-publish-direct-integration.md deleted file mode 100644 index bde89d2..0000000 --- a/docs/plans/cpk-019-publish-direct-integration.md +++ /dev/null @@ -1,99 +0,0 @@ -# Make direct publication integrate final work - -This ExecPlan is a living document. Maintain it according to the repository's `.agent/PLANS.md`. - -## Purpose / Big Picture - -After this change, `publish` has one complete result in direct-integration mode. The coordinator pushes the final reviewed branch, merges it into `main`, verifies the merge, and monitors required post-merge CI. A branch-only push is not a completed publication. - -## Progress - -- [x] (2026-08-14 18:31Z) Reproduced the wrong interpretation when CPK-018 publication stopped after branch push. -- [x] (2026-08-14 18:31Z) Identified the conflicting separate-authorization rule in every current policy owner. -- [x] (2026-08-14 18:31Z) Defined the behavior floor, scope ceiling, and direct-publication contract. -- [x] (2026-08-14 18:31Z) Created stacked task branch `cpk-019-publish-direct-integration` and activated CPK-019. -- [x] (2026-08-14 18:39Z) Corrected the publication policy owners and focused check. -- [x] (2026-08-14 18:39Z) Passed two focused tests, 28 full-suite tests, and Python compilation. -- [x] (2026-08-14 18:44Z) Validated documentation, shell syntax, diff, and checksums. -- [x] (2026-08-14 17:23Z) Completed clean-context review pass 2 with no findings. A local checkpoint is ready. - -## Surprises & Discoveries - -- Observation: The policy defines full integration only for PR mode. - Evidence: Direct mode requires separate authorization for branch push and merge, so `publish` can stop after the push. -- Observation: Review pass 1 found that nearby version guidance could make `publish` look like tag and GitHub release authority. - Evidence: Every current publication owner now excludes tag creation, GitHub releases, and cleanup. - -## Decision Log - -- Decision: In direct mode, one `publish` request authorizes push, merge to `main`, integration verification, and required post-merge CI. - Rationale: The user defines publication as final delivery when PR mode is unavailable. - Date/Author: 2026-08-14 / user and Codex -- Decision: Keep cleanup and release authority separate. - Rationale: Publication completes integration. It does not erase branches, remove worktrees, create tags, or create releases. - Date/Author: 2026-08-14 / Codex -- Decision: Keep version 0.11.0. - Rationale: This policy correction is part of the unpublished 0.11.0 candidate. - Date/Author: 2026-08-14 / Codex - -## Outcomes & Retrospective - -Implementation and documentation are complete. The focused policy checks and all 28 tests pass. Shell, diff, and checksum checks pass. Review pass 1 found one policy ambiguity, which was fixed without advancing the implementation-defect count. Fresh review pass 2 found no findings. The local checkpoint is ready, but push and integration are not authorized by this request. - -## Context and Orientation - -The task uses branch `cpk-019-publish-direct-integration`. Its base branch is `cpk-018-compact-agents-profile`, and its base commit is `3072bfd14b220db12e107900326cfb35a4ba8aca`. This branch is stacked because CPK-015 through CPK-018 are not integrated into `main`. - -PR mode means that repository protection, CI, and conversation rules enforce a pull request. In PR mode, `publish` already authorizes the path through squash merge and integration verification. - -Direct-integration mode applies when any PR-mode condition is absent. `assets/AGENTS.block.md`, `README.md`, `docs/OPERATING-MANUAL.md`, and `.agent/PLANS.md` currently require separate authorization for branch push and merge to `main`. `assets/hooks/session_start.py` says only to use direct integration. These owners let a coordinator interpret `publish` as branch push only. - -## Normal-Use Behavior Floor - -A task reaches publication only after validation, documentation, pre-commit review, and commit are complete. If PR mode is off, one explicit `publish` request authorizes the coordinator to push the task branch, merge it into `main`, push `main`, verify the integrated commit, and monitor required post-merge CI. - -If PR mode is active, the existing pull-request workflow remains authoritative. Publication in either mode ends only after verified integration. Cleanup, tag creation, GitHub release creation, and unrelated fixes require separate authority. - -## Scope Ceiling - -Do not change PR-mode detection or gates. Do not add a pull request when PR mode is off. Do not change review timing, version selection, tag rules, release rules, or cleanup rules. Do not automate merge mechanics in toolkit code. - -## Plan of Work - -Replace the separate branch-push and merge authorization rule in every current publication-policy owner. State that direct `publish` means final integration. Add the same compact rule to Session Start guidance. - -Update the publication consistency test in `tests/test_kit.py`. It must require the direct-mode contract across the managed agent block, Session Start hook, `PLANS.md`, README, and operating manual. Regenerate `MANIFEST.sha256` after content is final. - -## Concrete Steps - -Work from `/home/mbeutler/Projects/codex-practical-kit` on `cpk-019-publish-direct-integration`. - -Run: - - python3 -m unittest tests.test_kit.IntegrationTests.test_pr_publication_policy_is_consistent - ./run-tests.sh - sh -n doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh - git diff --check - sha256sum --check MANIFEST.sha256 - -Record results in `.agent/test-results/cpk-019-publish-direct-integration.md`. Never stage that file. - -## Validation and Acceptance - -The focused test must fail if direct `publish` can stop after branch push or still needs separate merge authority. The existing PR-mode assertions must continue to pass. - -A human reading each policy owner must see the same result: PR mode uses its pull-request workflow. Direct mode integrates final work into `main`. Neither mode includes cleanup or release work. - -## Idempotence and Recovery - -The policy edits are static text. Repeating validation is safe. Stop and report the first command failure. Do not add retry or recovery behavior. - -## Artifacts and Notes - -Preserve `.mcp.json`, `.repowise/`, and `.vscode/`. They are untracked environment state outside this task. - -## Interfaces and Dependencies - -No code interface or dependency changes. The public command contract is the meaning of the word `publish` in direct-integration mode. - -Revision note: Created after CPK-018 publication stopped at branch push and the user corrected the intended authority. Closed after clean review pass 2. diff --git a/docs/plans/cpk-020-protect-full-set-invariants.md b/docs/plans/cpk-020-protect-full-set-invariants.md deleted file mode 100644 index 7723d76..0000000 --- a/docs/plans/cpk-020-protect-full-set-invariants.md +++ /dev/null @@ -1,101 +0,0 @@ -# Protect full-set invariants from bounded samples - -This ExecPlan is a living document. Maintain it according to the repository's `.agent/PLANS.md`. - -## Purpose / Big Picture - -After this change, an agent cannot use a bounded raw-input sample to approve a result that depends on every matching record. Design Preflight states the full-set invariant before implementation. Correctness review challenges limits, sampling, and early success. One focused check uses duplicate prefix values followed by a different value. - -## Progress - -- [x] (2026-08-14 20:01Z) Reproduced the process defect from the supplied Microsoft renewal example. -- [x] (2026-08-14 20:01Z) Identified the managed policy, Design Preflight, and correctness lens as the outcome owners. -- [x] (2026-08-14 20:01Z) Defined the behavior floor, scope ceiling, and exact checks. -- [x] (2026-08-14 20:01Z) Created branch `cpk-020-protect-full-set-invariants` and activated CPK-020. -- [x] (2026-08-14 20:04Z) Corrected the policy owners and operating manual. -- [x] (2026-08-14 20:04Z) Passed the focused check, all 29 tests, Python compilation, shell lint, diff check, and checksum check. -- [x] (2026-08-14 20:04Z) Completed clean-context review pass 1 with no findings. A local checkpoint is ready. - -## Surprises & Discoveries - -- Observation: Ponytail already forbids simplifying explicit validation and requires correct edge-case behavior. - Evidence: The installed Ponytail skill says that the ladder runs after complete understanding and must not simplify explicit validation. -- Observation: A blanket ban on limits or early termination rejects correct implementations. - Evidence: `COUNT(DISTINCT value)`, `DISTINCT value LIMIT 2`, and stopping after the first proven violation preserve the required result. - -## Decision Log - -- Decision: Treat this as a process defect in invariant definition and review preparation. - Rationale: The implementation optimized before it expressed the requirement over the complete matching set. - Date/Author: 2026-08-14 / user and Codex -- Decision: Forbid successful full-set conclusions from bounded raw inputs. - Rationale: Duplicate prefix rows can hide a later counterexample. - Date/Author: 2026-08-14 / Codex -- Decision: Permit aggregates and bounded reads that preserve the full-set result. - Rationale: The rule must reject the faulty operation order without banning correct database operations. - Date/Author: 2026-08-14 / Codex -- Decision: Keep version 0.11.0. - Rationale: No `0.11.0` tag or GitHub release exists. A local checkpoint does not change the version. - Date/Author: 2026-08-14 / Codex - -## Outcomes & Retrospective - -The toolkit now defines one full-set rule across implementation policy, Design Preflight, correctness review, and the operating manual. The focused policy check and all 29 tests pass. Python compilation, shell lint, diff, and checksum checks pass. Clean-context review pass 1 found no findings. The local checkpoint is ready, but publication is not authorized by this request. - -## Context and Orientation - -The task uses branch `cpk-020-protect-full-set-invariants`. Its base branch is `main`, and its base commit is `33128b02ee2040c3dba2d527528b656fad013eb3`. The work uses one writable implementation stream in the current checkout. - -The reported defect used `LIMIT 2` on raw rows before duplicate renewal dates were removed. Two duplicate rows supported a false success result while a later distinct date remained unread. The requirement covered all matching products in the latest billing month. - -The toolkit-managed global policy is `assets/AGENTS.block.md`. The Session Start summary is `assets/hooks/session_start.py`. Design preparation is owned by `assets/skills/design-preflight/SKILL.md`. Correctness review prompts are owned by `assets/skills/adversarial-review/references/reviewer-lenses.md`. - -## Normal-Use Behavior Floor - -When an explicit requirement covers every matching record, the success path must use the complete set or a logically equivalent aggregate. It must not limit raw records before grouping, deduplication, or aggregation and then claim success. - -The implementation check must include duplicate prefix values followed by a later counterexample. A correct implementation rejects that data. Correct aggregates and short-circuit failure paths remain valid. - -## Scope Ceiling - -Do not ban all uses of `LIMIT`, sampling, or early termination. Do not add database-specific query guidance, runtime enforcement, a new skill, a new dependency, or a general combinatorial test checklist. Do not change review-cycle accounting or supported environmental conditions. - -## Plan of Work - -Add one compact full-set rule to the managed policy and Session Start summary. Add the detailed design obligation to Design Preflight. Add the matching challenge to the correctness reviewer lens. - -Add one integration test that requires the rule in each owner and preserves the managed-profile line limit. Update the operating manual with the durable process rule. Regenerate `MANIFEST.sha256` after all content is final. - -## Concrete Steps - -Work from `/home/mbeutler/Projects/codex-practical-kit` on `cpk-020-protect-full-set-invariants`. - -Run: - - python3 -m unittest tests.test_kit.IntegrationTests.test_full_set_invariants_reject_bounded_raw_samples - ./run-tests.sh - sh -n doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh - git diff --check - sha256sum --check MANIFEST.sha256 - -Record results in `.agent/test-results/cpk-020-protect-full-set-invariants.md`. Never stage that file. - -## Validation and Acceptance - -The focused check must fail if the managed policy, Session Start summary, Design Preflight, or correctness lens loses its role. The complete suite must pass. The managed global profile must remain below 100 installed lines. - -A reader must see that a raw sample cannot prove success for a complete-set requirement. The same reader must see that a correct aggregate or proven failure short-circuit remains allowed. - -## Idempotence and Recovery - -The policy edits are static text. Repeating validation is safe. Stop and report the first command failure. Do not add retry or recovery behavior. - -## Artifacts and Notes - -Preserve `.mcp.json`, `.repowise/`, and `.vscode/`. They are untracked environment state outside this task. - -## Interfaces and Dependencies - -No runtime interface or dependency changes. The public behavior is the toolkit's implementation and review policy for requirements over complete matching sets. - -Revision note: Created from a confirmed implementation shortcut that limited raw rows before deduplication and produced a false success result. Closed after clean review pass 1. diff --git a/docs/plans/cpk-021-severe-defect-stop-diagnostics.md b/docs/plans/cpk-021-severe-defect-stop-diagnostics.md deleted file mode 100644 index 8d75358..0000000 --- a/docs/plans/cpk-021-severe-defect-stop-diagnostics.md +++ /dev/null @@ -1,120 +0,0 @@ -# Diagnose severe defects at review stop gates - -This ExecPlan is a living document. Maintain it according to the repository's `.agent/PLANS.md`. - -## Purpose / Big Picture - -After this change, every validated finding that causes a review stop gets its own human decision block. A severe stop also runs one fresh read-only model diagnostic. The coordinator includes the complete diagnostic in the same final response before the halt. - -## Progress - -- [x] (2026-08-14 20:14Z) Reproduced the missing communication path in the third-defect breaker. -- [x] (2026-08-14 20:14Z) Selected a fresh diagnostic subagent as the model-query mechanism. -- [x] (2026-08-14 20:14Z) Defined the supported model, severe trigger, stop formatter, and halt boundary. -- [x] (2026-08-14 20:14Z) Created stacked branch `cpk-021-severe-defect-stop-diagnostics` and activated CPK-021. -- [x] (2026-08-14 20:43Z) Implemented the stop formatter and diagnostic skill. -- [x] (2026-08-14 20:43Z) Forward-tested the diagnostic skill with a duplicate-prefix severe defect. -- [x] (2026-08-14 20:43Z) Validated the complete pre-review candidate. -- [x] (2026-08-14 20:49Z) Completed clean-context review with no findings. Prepared the candidate for a local checkpoint. -- [x] (2026-08-14 21:32Z) Reopened CPK-021 after a real stop returned the handoffs without the required diagnostic. -- [x] (2026-08-14 21:39Z) Validated one atomic response with two handoffs, two diagnostic findings, one portable summary, and final status lines. -- [x] (2026-08-14 21:45Z) Completed fresh correctness review with no findings. Prepared the correction checkpoint. - -## Surprises & Discoveries - -- Observation: The reviewer JSON format and the human decision format have no routing rule between them. - Evidence: `adversarial-review` defines reviewer JSON and a final status line. It does not define per-finding stop output. -- Observation: The toolkit already has the required model-query mechanism. - Evidence: Adversarial Review uses one fresh read-only subagent per pass. A diagnostic can use the same coordinator capability after the reviewer closes. -- Observation: Component checks did not prove one complete severe-stop response. - Evidence: A real third-pass stop returned the decision handoffs and status before it returned the diagnostic. - -## Decision Log - -- Decision: Define P0 and P1 findings as severe on any pass. Also treat an implementation defect on the third counted pass as severe. - Rationale: P0 and P1 indicate high immediate impact. A third counted defect indicates a repeated process failure even when severity is P2. - Date/Author: 2026-08-14 / Codex -- Decision: Render one complete decision handoff for each stop-causing finding. - Rationale: A cumulative handoff hides each trigger, exposure, option set, recommendation, and required answer. - Date/Author: 2026-08-14 / user and Codex -- Decision: Query a fresh read-only subagent for diagnosis. - Rationale: This reuses the installed clean-context model path and adds no API key, service, CLI recursion, or runtime dependency. - Date/Author: 2026-08-14 / Codex -- Decision: Run the diagnostic before the final halt, then prohibit all implementation activity. - Rationale: The user needs the evidence summary before choosing a correction. - Date/Author: 2026-08-14 / user and Codex -- Decision: Keep version 0.11.0. - Rationale: No `0.11.0` tag or GitHub release exists. A local checkpoint does not change the version. - Date/Author: 2026-08-14 / Codex -- Decision: Complete and validate the diagnostic before composing the severe-stop final response. - Rationale: This makes diagnostic delivery a precondition of the halt status while preserving the required output order. - Date/Author: 2026-08-14 / user and Codex - -## Outcomes & Retrospective - -The atomic-response correction, validation, forward test, and clean-context review are complete. The fresh review found no validated defects. Publication is not authorized. - -## Context and Orientation - -The task uses branch `cpk-021-severe-defect-stop-diagnostics`. Its base branch is `cpk-020-protect-full-set-invariants`, and its base commit is `8f542e45e295`. The branch is stacked because CPK-020 is not integrated into `main`. - -`assets/skills/adversarial-review/SKILL.md` owns review validation, stop behavior, and final response assembly. `references/finding-format.md` owns reviewer JSON. The global communication rule in `assets/AGENTS.block.md` owns the human decision labels. - -The new `assets/skills/defect-diagnostic/` skill owns clean-context defect reconstruction. `kit.py` owns custom-skill installation. The coordinator remains the only agent that can spawn and close the diagnostic subagent. - -## Normal-Use Behavior Floor - -After the coordinator validates findings, a P0 or P1 finding stops automatic correction on any pass. An implementation defect on the third counted pass also stops automatic correction. - -At either severe stop, close the reviewer. Complete and validate the diagnostic before composing the final response. - -Run `defect-diagnostic` automatically. Give one fresh read-only subagent the raw requirement, implementation diff, source, checks, review history, and finding evidence. Omit reviewer fix directions. Do not give it the coordinator's diagnosis or proposed fix. The subagent retraces the decision sequence and produces the summary in the skill reference. - -In one final response, present each separate decision handoff first. Then present the complete diagnostic, its portable summary, and the final status lines. After that response, halt. Do not edit, test, review, commit, publish, run CI, change task state, or create follow-up work. - -## Scope Ceiling - -Do not restore a Stop hook. Do not call `codex exec`, the OpenAI API, or an external model service. Do not add credentials, a runtime script, persistent incident storage, automatic toolkit edits, or a diagnostic review loop. Do not trigger the automatic halt for P2 findings before the third counted pass. - -## Plan of Work - -Add a stop-finding formatter reference to Adversarial Review. Update its breaker so each stop finding uses that formatter. Add the severe trigger, diagnostic call, and mandatory halt. - -Create the `defect-diagnostic` skill with one portable output reference and standard UI metadata. Add it to the custom-skill installer. Add focused tests for installation, implicit invocation metadata, per-finding formatting, automatic triggers, and the halt boundary. - -Update the managed global policy, Session Start summary, README, review guide, and operating manual. Regenerate `MANIFEST.sha256` after content is final. - -## Concrete Steps - -Work from `/home/mbeutler/Projects/codex-practical-kit` on `cpk-021-severe-defect-stop-diagnostics`. - -Run: - - python3 /home/mbeutler/.codex/skills/.system/skill-creator/scripts/quick_validate.py assets/skills/defect-diagnostic - python3 -m unittest tests.test_kit.IntegrationTests.test_review_stop_diagnostics_are_per_finding_and_mandatory - ./run-tests.sh - sh -n doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh - git diff --check - sha256sum --check MANIFEST.sha256 - -Record results in `.agent/test-results/cpk-021-severe-defect-stop-diagnostics.md`. Never stage that file. - -## Validation and Acceptance - -The focused test must fail if the stop path combines findings, omits a communication label, skips the diagnostic trigger, permits a severe automatic fix, or omits the final halt. It must also fail if the new skill is absent from installation. - -A clean-context forward test must return one response with two separate handoffs, two diagnostic findings, one portable summary, and final status lines. The response must not end after a handoff question. - -## Idempotence and Recovery - -The skill and policy edits are static. Repeating validation is safe. Stop and report the first command failure. Do not add retry or recovery behavior. - -## Artifacts and Notes - -Preserve `.mcp.json`, `.repowise/`, and `.vscode/`. They are untracked environment state outside this task. - -## Interfaces and Dependencies - -`defect-diagnostic` is a new custom skill. It uses the coordinator's existing subagent capability. It has no code dependency or external service. - -Revision note: Created after third-pass findings were returned as a cumulative status instead of separate human decision handoffs. Reopened after the handoffs were correct but the final response omitted the diagnostic. diff --git a/docs/plans/cpk-022-systematic-runtime-scenarios.md b/docs/plans/cpk-022-systematic-runtime-scenarios.md deleted file mode 100644 index f6120bd..0000000 --- a/docs/plans/cpk-022-systematic-runtime-scenarios.md +++ /dev/null @@ -1,140 +0,0 @@ -# Derive runtime scenarios before implementation - -This ExecPlan is a living document. Maintain it according to `.agent/PLANS.md`. - -## Purpose / Big Picture - -After this change, Design Preflight derives normal-use runtime scenarios with a repeatable method. One fresh read-only challenger performs an independent derivation before implementation. Undefined normal-use outcomes stop planning instead of becoming accidental behavior. - -## Progress - -- [x] (2026-08-14 21:14Z) Compared systematic test-design methods and selected three scenario lenses. -- [x] (2026-08-14 21:18Z) Completed one clean-context planning challenge from raw workflow examples. -- [x] (2026-08-14 21:20Z) Received human decisions to require the challenge and stop on unresolved contracts. -- [x] (2026-08-14 21:48Z) Created stacked branch `cpk-022-systematic-runtime-scenarios` and activated CPK-022. -- [x] (2026-08-14 22:08Z) Implemented the scenario proof, independent challenge, durable ExecPlan rules, compact policy, documentation, and focused test. -- [x] (2026-08-14 22:21Z) Forward-tested scheduled-worker, date-input, persistent-event, and collection-decision workflows. Retested date input after correcting the result schema. -- [x] (2026-08-14 22:28Z) Passed skill validation, the focused integration test, all 31 tests, shell syntax checks, diff checks, and the 94-line profile limit. Updated the authoritative documentation. -- [x] (2026-08-14 22:39Z) Corrected two validated pass-1 findings and confirmed that a prospective path remains applicable without a current implementation. -- [x] (2026-08-14 22:48Z) Reached a clean third review pass after two pass-1 implementation corrections and one pass-2 documentation correction. Prepared the local checkpoint. - -## Surprises & Discoveries - -- Observation: The current preflight derives no general boundary scenarios. - Evidence: `assets/skills/design-preflight/SKILL.md` defines ownership, scope, and one complete-set rule only. -- Observation: The optional preflight reviewer receives the coordinator's card. - Evidence: This packet can anchor the reviewer to scenarios that the coordinator already found. -- Observation: The existing reviewer schema cannot preserve an undefined normal-use outcome. - Evidence: It drops a result when the explicit-requirement value is false. -- Observation: Defect-style applicability fields made valid scenarios claim that they violated a requirement. - Evidence: The first forward tests had to set `violates_explicit_requirement` to `true` for correct expected results. The schema now asks whether a result is defined instead. -- Observation: Review found that the legacy current-path reproduction gate conflicted with prospective scenario feasibility. - Evidence: A planned normal-use path could fail the old gate before implementation even when its trigger was feasible without fault injection. -- Observation: Review found that a runtime preflight could require a Scenario Proof without independently requiring an ExecPlan. - Evidence: The temporary card was merged only for work that already met the narrower ExecPlan triggers. - -## Decision Log - -- Decision: Use input-domain, path-and-transition, and collection-semantics lenses. - Rationale: These lenses derive the supplied date, cutoff, orphan-state, filter, and cardinality cases without a universal checklist. - Date/Author: 2026-08-14 / user and Codex -- Decision: Require one independent challenge for every Design Preflight that covers non-trivial runtime behavior. - Rationale: The implementer's own experience is not a reliable scenario generator. - Date/Author: 2026-08-14 / user -- Decision: Start the challenger without inherited task conversation. - Rationale: Raw requirements and source reduce anchoring from the coordinator's proposed checks or correction. - Date/Author: 2026-08-14 / Codex -- Decision: Stop planning when supported normal use has no explicit result. - Rationale: The coordinator must not invent public behavior. - Date/Author: 2026-08-14 / user -- Decision: Keep version 0.11.0. - Rationale: No `0.11.0` tag or GitHub release exists. This branch is stacked on unpublished work. - Date/Author: 2026-08-14 / Codex -- Decision: Use trigger feasibility for all Design Preflight requirements and require one ExecPlan for every non-trivial runtime preflight. - Rationale: Prospective behavior cannot reproduce a current defect, and the accepted Scenario Proof needs one durable owner. - Date/Author: 2026-08-14 / Codex, review pass 1 - -## Outcomes & Retrospective - -Implementation, independent forward testing, corrections, validation, documentation, and clean review are complete. The change is ready for its local checkpoint. Publication is not authorized. - -The final reviewer found no defects. Pass 1 found two implementation-policy conflicts. Pass 2 found one documentation inconsistency, which did not increment or reset the defect count. Pass 3 was clean. - -## Context and Orientation - -The task uses branch `cpk-022-systematic-runtime-scenarios`. Its base branch is `cpk-021-severe-defect-stop-diagnostics`, and its base commit is `b36de27`. - -`assets/skills/design-preflight/SKILL.md` owns the pre-implementation process. Its `references/preflight-card.md` owns the temporary card. Its `references/preflight-review.md` owns challenger output. `.agent/PLANS.md` owns the durable ExecPlan contract. The accepted scenario proof must move into the ExecPlan. It must not create a second durable plan. - -## Supported Operating Model - -One coordinator reads repository source and writes one preflight. One fresh read-only challenger derives scenarios independently. The coordinator compares both results once. Small changes with one proven owner and one direct check continue to skip Design Preflight. - -Exclude I/O faults, permission changes, concurrency, interruption, retry, recovery, hostile input, outside writers, and external outages unless the task includes them. - -## Scenario Proof - -For each changed runtime outcome, trace the entry point through relevant gates to its terminal owner. Derive only feasible cases from three lenses. - -The input-domain lens covers presence, syntax, semantic validity, range boundaries, and explicit relationships. The path-and-transition lens covers selectors, filters, transformations, controlled time boundaries, state transitions, and terminal obligations. The collection lens covers supported empty input, one record, duplicates, a duplicate prefix with a later counterexample, and every record that owes a terminal result. - -A retained scenario has a source requirement, a concrete trigger, an expected result, and a runnable check. An inapplicable lens has one short reason. Do not combine all inputs into a Cartesian product. - -If normal use, project control, and trigger feasibility without fault injection are true but no explicit result exists, record a contract gap. Stop for human direction before implementation. Do not classify the gap as a defect or invent an outcome. - -The challenger receives raw requirements, the supported model, exclusions, source locations, owners, gates, and current tests. It does not receive the coordinator's card, scenarios, implementation, previous diagnostics, corrections, severity, or preferred outcome. - -## Scope Ceiling - -Do not add a new skill, runtime script, service, dependency, persistent scenario database, universal edge-case checklist, fuzzing mandate, exhaustive input product, multiple challenger loop, or special zero-delta rule. Do not remove the direct-fix exception. - -## Plan of Work - -Update Design Preflight to require the independent challenge for non-trivial runtime behavior. Replace the anchored reviewer packet with raw evidence. Apply the supported-model gate once. Merge accepted scenarios into the preflight and ExecPlan. - -Expand the existing preflight card with one concise Scenario Proof section. Update the existing reviewer reference with `scenarios`, `contract_gaps`, `exclusions`, and `coverage` outputs. Do not add another reference file. - -Update `.agent/PLANS.md`, the compact global policy, and Session Start guidance. Add one focused integration test. Update the README, operating manual, and design rationale. Regenerate `MANIFEST.sha256` after content is final. - -## Concrete Steps - -Work from `/home/mbeutler/Projects/codex-practical-kit`. - -Run: - - python3 /home/mbeutler/.codex/skills/.system/skill-creator/scripts/quick_validate.py assets/skills/design-preflight - python3 -m unittest tests.test_kit.IntegrationTests.test_runtime_scenario_preflight_is_independent_and_durable - ./run-tests.sh - sh -n doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh - git diff --check - sha256sum --check MANIFEST.sha256 - -Record detailed results in `.agent/test-results/cpk-022-systematic-runtime-scenarios.md`. Never stage that file. - -## Validation and Acceptance - -Forward-test raw scheduled-worker, date-input, persistent-event, and collection-decision artifacts. The challenger must find the applicable scenario classes without receiving the expected cases. It must preserve an undefined supported result as a contract gap. It must exclude unsupported environmental failures. - -The focused test must fail if the challenge is optional for non-trivial runtime behavior, inherits the coordinator's proposed scenarios, lacks contract gaps, permits implementation with an unresolved contract, omits a lens, creates a second artifact, or removes the direct-fix exception. - -The managed AGENTS source must remain below 100 lines. One fresh correctness reviewer must inspect the cumulative diff from `b36de27`. - -## Idempotence and Recovery - -The changes are static policy and documentation. Repeating validation is safe. If a command fails, stop and report it. Do not add retry or recovery behavior. - -## Artifacts and Notes - -Preserve `.mcp.json`, `.repowise/`, and `.vscode/`. They are untracked environment state outside this task. - -## Interfaces and Dependencies - -The challenger JSON uses `reviewer`, `scenarios`, `contract_gaps`, `exclusions`, and `coverage`. A scenario requires normal use, project control, a feasible trigger without fault injection, and a defined result. A contract gap has the first three values and no defined result. - -No public command, runtime dependency, or external service changes. - -Revision note: Created from the accepted conversational plan and clean-context planning challenge. -Revision note: Recorded implementation, four unrelated forward tests, and the corrected scenario applicability schema. -Revision note: Recorded the pass-1 corrections and prospective-path retest. -Revision note: Corrected one pass-2 review-housekeeping inconsistency in this ExecPlan. -Revision note: Recorded clean review closure and local checkpoint readiness. Publication remains unauthorized. diff --git a/docs/plans/cpk-023-owner-composition-proof.md b/docs/plans/cpk-023-owner-composition-proof.md deleted file mode 100644 index c876009..0000000 --- a/docs/plans/cpk-023-owner-composition-proof.md +++ /dev/null @@ -1,163 +0,0 @@ -# Enforce single rule ownership - -This ExecPlan is a living document. Maintain it in accordance with `.agent/PLANS.md`. - -## Purpose / Big Picture - -After this change, the managed `AGENTS.md` is a compact router. It links an agent to the complete rule file that applies to the current task. The Session Start hook does not inject another policy copy. A runnable ownership check fails when a protected rule appears outside its sole live owner. - -## Progress - -- [x] (2026-08-15 04:15Z) Proved that local `main` and `origin/main` equal `7e8190d7194605d917c1b03afd3e9a25253a2b42`. -- [x] (2026-08-15 04:15Z) Created `cpk-023-owner-composition-proof` and activated CPK-023. -- [x] (2026-08-15 04:30Z) Implemented and validated the first copied-policy design. -- [x] (2026-08-15 05:10Z) Stopped after three counted review passes exposed repeated propagation defects. -- [x] (2026-08-15 05:20Z) Completed the severe-defect diagnostic and obtained human direction. -- [x] (2026-08-15 05:35Z) Replaced the design with focused rule owners and an AGENTS router. -- [x] (2026-08-15 06:15Z) Implemented the replacement architecture and its ownership check. -- [x] (2026-08-15 06:20Z) Finalized documentation, validation, and roadmap state. -- [x] (2026-08-15 07:00Z) Corrected the three replacement-review pass-1 defects and repeated full validation. -- [x] (2026-08-15 07:25Z) Completed replacement review pass 2. It found two P2 ownership-check defects. -- [x] (2026-08-15 07:35Z) Moved the remaining one-attempt copies to a canonical route and made the link-only check cover the complete section. -- [x] (2026-08-15 07:40Z) Repeated skill, unit, shell, hook, diff, and checksum validation after the pass-2 corrections. -- [x] (2026-08-15 08:05Z) Rejected the replacement pass-3 finding because the internal Playground exercise is not a supported normal-use rule surface. -- [x] (2026-08-15 08:10Z) Corrected the Playground exercise wording and removed it from the distribution manifest. -- [x] (2026-08-15 08:15Z) Repeated skill, unit, shell, hook, diff, checksum, and manifest-scope validation. -- [x] (2026-08-15 08:45Z) Limited review stop accounting to executable production code by human direction. -- [x] (2026-08-15 08:50Z) Bound each marked route to a resolved file that declares the same owner. -- [x] (2026-08-15 09:00Z) Validated the production-code gate and complete route invariant. -- [x] (2026-08-15 09:20Z) Completed fresh review. It found one non-counting ExecPlan housekeeping issue. -- [x] (2026-08-15 09:25Z) Replaced the copied supported-model text with its canonical link. -- [x] (2026-08-15 09:30Z) Validated the housekeeping correction. -- [x] (2026-08-15 09:40Z) Completed fresh review pass 5 with no findings. -- [x] (2026-08-15 09:45Z) Prepared the reviewed candidate for the authorized local checkpoint commit. - -## Surprises & Discoveries - -- Observation: The old tests required identical policy sentences in several files. - Evidence: `tests/test_kit.py` calls AGENTS, Session Start, PLANS, skills, and documentation policy owners and asserts the same text in each one. -- Observation: Compactness made the copied rules lose required facts. - Evidence: Each review correction expanded one copy and left another copy incomplete. -- Observation: The installer already owns a complete skill-copy lifecycle. - Evidence: Custom skills support conflict detection, reinstall, uninstall, and doctor checks through manifest schema 1. -- Observation: The committed source version is `0.11.0`. - Evidence: The branch changes `KIT_VERSION` to `0.11.1`, which is the correct bug-fix increment. -- Observation: A repository-level rule link cannot safely use invocation defaults after a custom-path installation. - Evidence: `setup-repo` has no path options, while the global AGENTS router already owns the required link. -- Observation: Link migration must remove semantic copies, not only exact guard phrases. - Evidence: Replacement review pass 1 found the four supported-model checks restated in Design Preflight and its card. -- Observation: Moving a policy requires a fact-by-fact transfer from every former live owner. - Evidence: Replacement review pass 1 found accepted pull-request gates that were absent from the new publication owner. -- Observation: A fixed list of current manuals can omit a live rule copy. - Evidence: Replacement review pass 2 found the one-attempt rule in `docs/REMOVE-CBM.md`, which the ownership scan did not include. -- Observation: A marker-level parser does not protect prose before the marker. - Evidence: Replacement review pass 2 inserted ordinary prose between a section heading and its route marker without invalidating the original check. -- Observation: A distributed-file checksum does not make an internal exercise a live agent rule surface. - Evidence: The user rejected the replacement pass-3 finding because `PLAYGROUND.md` is a special-case exercise and does not affect supported real-world usage. -- Observation: Executable test logic is not executable production code. - Evidence: The user clarified that tests and fixtures can require correction but cannot increment the review breaker or trigger a stop. - -## Decision Log - -- Decision: Use one managed rule package with focused Markdown references. - Rationale: The existing skill lifecycle installs and removes the package without a second file-management system. - Date/Author: 2026-08-15 / User and Codex -- Decision: Make the managed AGENTS block a trigger-and-link router. - Rationale: Agents can read only the complete rule that applies to the current task. - Date/Author: 2026-08-15 / User and Codex -- Decision: Treat Session Start as an activation notice only. - Rationale: Session Start cannot become another policy owner. - Date/Author: 2026-08-15 / User and Codex -- Decision: Protect canonical rules with unique owner markers and owner-local guard phrases. - Rationale: One generic check can reject copied live policy without copying expected policy into the test. - Date/Author: 2026-08-15 / Codex -- Decision: Keep version `0.11.1`. - Rationale: This work corrects the failed CPK-023 bug fix. It does not add a user capability. - Date/Author: 2026-08-15 / User and Codex -- Decision: Count only defects in executable production code for review stop gates. - Rationale: Tests, fixtures, documentation, configuration, dependencies, manifests, and housekeeping do not run as production code. - Date/Author: 2026-08-15 / User - -## Outcomes & Retrospective - -The first implementation is rejected. It strengthened the required rule but made every policy copy another authority. - -The replacement installs 12 focused shared-rule files. AGENTS is a 25-line router, and Session Start is one activation notice. Existing skills and the active ExecPlan link shared rules instead of copying them. One generic check rejects duplicate owners, copied guards, extra route content, missing targets, and wrong-owner targets. The review breaker counts only executable production-code defects. All seven custom skills and all 27 tests pass. Fresh review pass 5 found no findings. - -## Context and Orientation - -The task uses branch `cpk-023-owner-composition-proof`. Its base is `main` at `7e8190d7194605d917c1b03afd3e9a25253a2b42`. - -`assets/AGENTS.block.md` is the source for the global managed block. `assets/hooks/session_start.py` supplies startup context. `kit.py` stages custom skills before it writes AGENTS. `tests/test_kit.py` owns installer and policy checks. - -The new package lives at `assets/skills/codex-practical-kit-rules/`. Its reference files are the only live owners of shared toolkit rules. Existing skill files remain the owners of their specialized procedures. Historical ExecPlans and diagnostics are records, not live instruction sources. - -## Design Preflight - -The required outcome is one complete owner for each live rule and an installed router that reaches that owner. The project controls the rule sources, installer, generated links, tests, and documentation. - -Apply [Supported model](../../assets/skills/codex-practical-kit-rules/references/supported-model.md). This task also supports installation with distinct Codex and skills directories. - -This is a non-runtime policy architecture change. The user resolved the ownership contract. A planning challenger is not required. - -The implementation ceiling excludes a policy parser, generated documentation system, new dependency, manifest schema change, or semantic prose classifier. One stdlib test will scan explicit owner and guard markers. - -Preflight: ready — reuse the custom-skill lifecycle, render direct AGENTS links, and enforce unique live owners. - -## Plan of Work - -First, create the focused rule package. Move each accepted shared policy into one file. Add a short package `SKILL.md` that tells agents to read only the reference selected by AGENTS. Add owner and guard comments to each canonical file. - -Next, replace the managed AGENTS content with a short route table. Render the skills and PLANS paths during installation. Replace the Session Start policy copy with one activation notice. - -Then, remove copied shared rules from PLANS, custom skills, templates, README, the operating manual, and the design rationale. Link to the canonical source instead. Keep operational commands and product facts that are not agent rules. - -Finally, replace every propagation test with single-owner content checks, link-resolution checks, and one general duplication guard. Update source version statements and checksums. Finalize documentation before review. - -## Concrete Steps - -Work in `/home/mbeutler/Projects/codex-practical-kit`. - -Run: - - python3 /home/mbeutler/.codex/skills/.system/skill-creator/scripts/quick_validate.py assets/skills/codex-practical-kit-rules - python3 -m unittest tests.test_kit.InstallerTests.test_global_agents_profile_is_compact_and_subagent_safe - python3 -m unittest tests.test_kit.IntegrationTests.test_rule_owners_are_unique - ./run-tests.sh - sh -n doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh - git diff --check - sha256sum --check MANIFEST.sha256 - -Record detailed output in `.agent/test-results/cpk-023-owner-composition-proof.md`. Do not stage that ignored file. - -## Validation and Acceptance - -The installed AGENTS block must contain only routing text and links. Each rendered link must target the configured installation paths and exist after installation. Session Start must contain no expanded policy. - -Each live owner identifier must occur once. Each owner-local guard phrase must occur only in that owner across current policy and documentation surfaces. Historical task records are excluded. - -The canonical owner-composition rule must preserve the three accepted composed runtime obligations. It must link the full-set rule instead of copying it. - -The full unit suite, skill validation, shell syntax, diff, and checksum checks must pass. One fresh adversarial reviewer must find no supported normal-use defect before commit. - -## Idempotence and Recovery - -Reinstall replaces only toolkit-owned skill directories and the managed AGENTS block. Uninstall removes only manifest-recorded destinations. If any command fails, stop and report it. - -## Artifacts and Notes - -Preserve the existing untracked `.claude/`, `.codex/`, `.mcp.json`, `.repowise/`, `.vscode/`, and root `AGENTS.md` paths. They are environment state outside this task. - -## Interfaces and Dependencies - -The installed AGENTS contract changes from embedded policy to absolute local links. The installer adds one managed rule package. No CLI, configuration schema, external service, or dependency changes. The toolkit version becomes `0.11.1`. - -Revision note: Replaced the rejected copied-policy design after the third review defect and human direction. -Revision note: Recorded the validated replacement candidate and fresh-review readiness. -Revision note: Recorded the three replacement-review pass-1 findings and correction scope. -Revision note: Recorded the shared-owner corrections and repeated validation before replacement review pass 2. -Revision note: Recorded the two replacement-review pass-2 findings and their shared-check corrections. -Revision note: Recorded the rejected pass-3 finding and the user-defined Playground scope. -Revision note: Recorded the production-code-only stop gate and the corrected route invariant. -Revision note: Replaced the active plan's copied supported-model text after a non-counting housekeeping finding. -Revision note: Recorded the clean final review result. diff --git a/docs/plans/cpk-024-product-scope-boundaries.md b/docs/plans/cpk-024-product-scope-boundaries.md deleted file mode 100644 index 2eb4daf..0000000 --- a/docs/plans/cpk-024-product-scope-boundaries.md +++ /dev/null @@ -1,87 +0,0 @@ -# Bind reviews to documented product scope - -This ExecPlan is a living document. Maintain it according to `.agent/PLANS.md`. - -## Purpose / Big Picture - -After this change, planning and correctness review use the product's documented boundary. Reviewers can examine owners that the task composes, protect current behavior of opaque owners, and exclude deferred placeholders. This prevents review from creating future product obligations. - -## Progress - -- [x] (2026-08-15 20:48Z) Created branch `cpk-024-product-scope-boundaries` from `a5766bf3d8be20bc5342eeeefd8b9815ffc82dea`. -- [x] (2026-08-15 20:48Z) Activated CPK-024 in `docs/roadmap.md`. -- [x] (2026-08-15 20:51Z) Added the canonical scope-boundary owner and linked its planning and review consumers. -- [x] (2026-08-15 20:51Z) Updated tests, documentation, version `0.12.0`, and `MANIFEST.sha256`. -- [x] (2026-08-15 20:55Z) Validated, received a clean pass-1 review, and closed the roadmap. The local checkpoint commit follows this record update. - -## Surprises & Discoveries - -- Observation: RepoWise retrieval succeeded, but its index predates the current commit and has no prose provider. - Evidence: It reported indexed commit `7e8190d71946` and live commit `a5766bf3d8be`. - -## Decision Log - -- Decision: Keep one canonical owner at `assets/skills/codex-practical-kit-rules/references/scope-boundaries.md`. - Rationale: Rule ownership forbids summaries of a shared rule in live consumers. - Date/Author: 2026-08-15 / Codex and user. -- Decision: Keep the main coordinator as the implementer on one task branch. - Rationale: This policy change has one implementation stream and no independent writable components. - Date/Author: 2026-08-15 / Codex and user. -- Decision: Use version `0.12.0`. - Rationale: This adds a toolkit capability before `1.0.0`, so it increments the minor version. - Date/Author: 2026-08-15 / Codex and user. - -## Outcomes & Retrospective - -CPK-024 added one canonical scope owner and linked its planning and review consumers. The focused tests, all 28 repository tests, skill validation, shell checks, diff check, and manifest check passed. The clean-context correctness review returned no findings on pass 1. No runtime, dependency, configuration, or project-specific special case was added. - -## Context and Orientation - -The managed rules package stores shared policy in focused files under `assets/skills/codex-practical-kit-rules/references/`. Design Preflight owns task analysis. Adversarial Review owns correctness review. Their templates carry task facts, while shared rules remain in one owner. - -The product boundary for this task comes from the user's accepted correction plan. The task composes Design Preflight, ExecPlans, and Adversarial Review. Existing rule owners are opaque unless this task changes their links. No deferred product capability is promoted. Meridian and its set-aside implementation are validation context only; they are not toolkit-specific requirements. - -## Scenario Proof - -This change does not add runtime behavior. No runtime Scenario Proof is required. The user resolved the product boundary and owner classifications before implementation, so no planning challenger is required. - -## Plan of Work - -Add one focused scope-boundary rule. Link Design Preflight and Adversarial Review to it. Extend their factual templates with boundary sources, owner classifications, changed production entry points, and task-visible outcomes. Keep the definitions and gate behavior only in the new owner. - -Update the rule lists, focused tests, source version, and manifest. Update user documentation only where the new rule must be discoverable. Do not add a runtime, dependency, configuration option, or project-specific special case. - -## Concrete Steps - -Work from `/home/mbeutler/Projects/codex-practical-kit` on branch `cpk-024-product-scope-boundaries`. Edit files with exact patches. Run: - - ./run-tests.sh - sh -n doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh - git diff --check - sha256sum --check MANIFEST.sha256 - -Expect every command to exit with status zero. - -## Validation and Acceptance - -The tests must prove that the new rule has one owner, every required consumer links to it, the review schema requires the scope trace, and the package has 13 focused rule files. Manual inspection must show that deferred owners cannot produce findings unless the task promotes them. - -Run one clean-context adversarial review after documentation and roadmap preparation. A clean result permits review closure and a local checkpoint commit. This task does not authorize push, tag, release, integration, or branch cleanup. - -## Idempotence and Recovery - -Tests and validation commands are safe to repeat. If a command fails, keep CPK-024 Active and fix only the demonstrated cause. Do not publish partial work. - -## Artifacts and Notes - -The ignored test record will be `.agent/test-results/cpk-024-product-scope-boundaries.md`. It can mention Meridian only as an external validation scenario. Shipped rules and tests must stay product-neutral. - -## Interfaces and Dependencies - -The change adds Markdown policy and schema fields. It adds no library, service, command, or runtime interface. - -Revision note: Created the implementation plan from the accepted CPK-024 correction plan. - -Revision note: Recorded the implemented policy surface and successful pre-review validation. - -Revision note: Recorded the clean pass-1 review and completed roadmap transition. diff --git a/docs/plans/cpk-026-review-checkpoints.md b/docs/plans/cpk-026-review-checkpoints.md deleted file mode 100644 index 16a1afe..0000000 --- a/docs/plans/cpk-026-review-checkpoints.md +++ /dev/null @@ -1,102 +0,0 @@ -# Review only new fixes after the first pass - -This ExecPlan is a living document. Maintain it according to `.agent/PLANS.md`. - -## Purpose / Big Picture - -After this change, a review finding does not cause every later reviewer to inspect the full task again. Git identifies each staged candidate with a tree hash. Later reviewers inspect only the fix delta and its direct impact. One final coherence pass checks interactions across the task. - -## Progress - -- [x] (2026-08-16 00:53Z) Created branch `cpk-026-review-checkpoints` from `5c0d7b01fc78e86fb108f715c9b6a17399ae30ce`. -- [x] (2026-08-16 00:53Z) Activated CPK-026 and placed CPK-027 next in `docs/roadmap.md`. -- [x] (2026-08-16 00:55Z) Added the checkpoint workflow and review packet fields. -- [x] (2026-08-16 00:55Z) Updated focused tests, version `0.13.0`, and checksums. -- [x] (2026-08-16 01:18Z) Passed validation and correctness review after two reviewed corrections. -- [x] (2026-08-16 01:19Z) Prepared the reviewed CPK-026 checkpoint candidate for commit. - -## Surprises & Discoveries - -- Observation: `git write-tree` creates a deterministic tree from the current index. - Evidence: The installed Git manual states that the index must be fully merged and updated first. -- Observation: The first review found that staging before checkpoint validation could absorb an unrelated tracked edit into a fix delta. - Evidence: Review finding R1 cited the ordering in `assets/skills/adversarial-review/SKILL.md`. -- Observation: The coherence review found that generic clean-result closure could close a task after an intermediate fix delta. - Evidence: Review finding R2 composed Adversarial Review with Roadmap Maintainer and Review Closure. - -## Decision Log - -- Decision: Store review checkpoint facts in the existing ignored task review record. - Rationale: This reuses the current evidence owner and adds no runtime or tracked ledger. - Date/Author: 2026-08-16 / Codex and user. -- Decision: Use the staged Git tree hash as the candidate identity. - Rationale: Git already provides the deterministic content address. A custom hashing tool is unnecessary. - Date/Author: 2026-08-16 / Codex and user. -- Decision: Use version `0.13.0`. - Rationale: Review checkpoints add a toolkit feature before version `1.0.0`. - Date/Author: 2026-08-16 / Codex and user. - -## Outcomes & Retrospective - -Version `0.13.0` now identifies staged candidates with Git tree hashes. A full pass found one pre-stage invalidation gap. The fix delta passed. The final coherence pass found one premature-closure conflict, and its correction delta passed. No residual risk remains. - -## Context and Orientation - -`assets/skills/adversarial-review/SKILL.md` owns the review procedure. Its `references/review-packet.md` owns reviewer inputs. Its `references/reviewer-lenses.md` defines review lenses. Detailed task results already live in ignored `.agent/test-results/` files. - -The initial review uses the full staged task candidate. If it reports findings, the result record stores that tree hash and the validated findings. A later review compares the prior tree with the current staged tree. It reads direct impact around that delta but does not reopen unrelated unchanged code. - -## Product Boundary - -Apply [Scope boundaries](../../assets/skills/codex-practical-kit-rules/references/scope-boundaries.md). CPK-026 composes Adversarial Review and its templates. Git installation, product code, and unrelated toolkit skills are opaque. No deferred capability is promoted. - -## Scenario Proof - -This task changes an agent procedure, not runtime product behavior. No runtime Scenario Proof is required. The user resolved the ownership and review boundaries before implementation. - -## Plan of Work - -Extend the existing review skill. Require an exact staged candidate and use `git write-tree` to identify it. Define full, delta, and coherence modes. Add the checkpoint facts to the review packet. Keep all checkpoint rules in the review skill. - -Add one focused repository test for the workflow. Update `KIT_VERSION` to `0.13.0`. Regenerate `MANIFEST.sha256` after the task documentation is final. - -## Concrete Steps - -Work from `/home/mbeutler/Projects/codex-practical-kit` on branch `cpk-026-review-checkpoints`. Run: - - ./run-tests.sh - sh -n doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh - git diff --check - sha256sum --check MANIFEST.sha256 - -Expect every command to exit with status zero. - -## Validation and Acceptance - -The first review must cover the full staged task. If it has findings, the next pass must compare staged tree hashes and inspect only the fix delta and its direct impact. After a clean delta review, one coherence pass must inspect interactions across the cumulative task. If the first full review is clean, it is final. - -The focused test must fail when checkpoint identity, delta review, unchanged-code protection, or final coherence is absent. - -## Idempotence and Recovery - -Validation commands are safe to repeat. A changed requirement, scope, base, supported model, or unrelated tracked file invalidates the checkpoint. Classify tracked worktree changes before staging a later candidate. In an invalidation case, restart with a full review. - -## Artifacts and Notes - -Store detailed results in `.agent/test-results/cpk-026-review-checkpoints.md`. Do not stage that record. - -## Interfaces and Dependencies - -Use the installed Git CLI. Add no dependency, script, service, or persistent tracked state. - -Revision note: Created the plan from the accepted review-checkpoint design. - -Revision note: Recorded the implemented review modes and focused test. - -Revision note: Recorded successful pre-review validation. - -Revision note: Required pre-stage tracked-change classification after review finding R1. - -Revision note: Limited review closure to final checkpoint results after coherence finding R2. - -Revision note: Recorded the final clean review and completed roadmap transition. diff --git a/docs/plans/cpk-027-lifecycle-skills.md b/docs/plans/cpk-027-lifecycle-skills.md deleted file mode 100644 index 9e529f1..0000000 --- a/docs/plans/cpk-027-lifecycle-skills.md +++ /dev/null @@ -1,101 +0,0 @@ -# Route toolkit rules through lifecycle skills - -This ExecPlan is a living document. Maintain it according to `.agent/PLANS.md`. - -## Purpose / Big Picture - -After this change, the managed AGENTS block names applicable skills instead of linking to a general rule package. Each skill loads only the focused rules needed for its lifecycle task. Every live rule still has one authoritative file. - -## Progress - -- [x] (2026-08-16 01:21Z) Created branch `cpk-027-lifecycle-skills` from CPK-026 checkpoint `37bdba5999615930d10ed03db1ddefea00b20cd0`. -- [x] (2026-08-16 01:22Z) Activated CPK-027 and mapped all 13 shared rule owners to lifecycle skills. -- [x] (2026-08-16 01:34Z) Migrated the rule owners, installer registration, router, tests, and current documentation. -- [x] (2026-08-16 01:39Z) Passed tests, nine skill validations, shell checks, manifest verification, and a six-case clean-context trigger test. -- [x] (2026-08-16 01:45Z) Passed the first full correctness review with no findings and prepared the reviewed candidate for commit. -- [ ] Install the exact commit live and publish version `0.14.0`. - -## Surprises & Discoveries - -- Observation: The installed RepoWise CLI supports index refresh but not the MCP-only `get_answer` command. - Evidence: `repowise update --no-agents` indexed checkpoint `37bdba59`; `repowise get_answer` returned `No such command`. - -## Decision Log - -- Decision: Create four missing lifecycle skills and extend two existing skills. - Rationale: This removes the catch-all package without creating one skill for each small reference. - Date/Author: 2026-08-16 / Codex and user. -- Decision: Use version `0.14.0`. - Rationale: Moving rule activation into lifecycle skills is a new pre-1.0 toolkit feature after committed version `0.13.0`. - Date/Author: 2026-08-16 / Codex and user. - -## Outcomes & Retrospective - -Version `0.14.0` passed validation, clean-context trigger testing, and full correctness review without findings. The managed AGENTS block names skills instead of detailed rule paths. Four new lifecycle skills and two existing skills own the migrated references. The installer removes the obsolete general package. Current manuals link to the new owners. No residual risk remains. - -## Context and Orientation - -`assets/AGENTS.block.md` is the managed router. Lifecycle skills now contain the 13 canonical shared rule owners. `kit.py` selects installed skills and removes the obsolete general package during upgrade. `tests/test_kit.py` verifies unique owners, valid links, installation, and versioning. - -The migration groups owners as follows: - -- `delivery-lifecycle`: coordination, delivery lifecycle, Git isolation, and decision handoffs. -- `design-preflight`: scope boundaries, supported model, owner composition, and full-set results. -- `adversarial-review`: review closure. -- `publication`: publication and versioning. -- `repository-knowledge`: repository knowledge. -- `toolkit-maintainer`: rule ownership. - -## Product Boundary - -CPK-027 composes the managed router, canonical rule owners, skill installation, current manuals, and ownership validation. Historical completed ExecPlans remain records. Runtime RepoWise behavior and unrelated toolkit procedures are opaque. - -## Scenario Proof - -This task changes instruction activation and installation, not application runtime behavior. No runtime Scenario Proof is required. Focused installer and rule-owner tests prove the supported results. - -## Plan of Work - -Move each canonical owner into the lifecycle skill that needs it. Keep references focused. Give each new skill a precise triggering description. Update all live links. Replace AGENTS file links with skill names and retain the ExecPlan path because it is not a skill. - -Register the four new skills, retire `codex-practical-kit-rules` during upgrade, and update the installer assertions. Preserve the owner and guard tests so duplicate rule text still fails. - -Update current documentation for the new skill layout. Do not rewrite historical ExecPlans solely to change old paths. Set `KIT_VERSION` to `0.14.0` and regenerate checksums. - -## Concrete Steps - -Work from `/home/mbeutler/Projects/codex-practical-kit` on branch `cpk-027-lifecycle-skills`. Run: - - ./run-tests.sh - python3 /home/mbeutler/.codex/skills/.system/skill-creator/scripts/quick_validate.py assets/skills/ - sh -n doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh - git diff --check - sha256sum --check MANIFEST.sha256 - -Expect each command to exit with status zero. - -## Validation and Acceptance - -The installed managed AGENTS block must route tasks to skill names without linking to rule references. Every canonical owner must occur once under an applicable skill. Every live Markdown link must resolve. Reinstallation must install the new skills and remove the obsolete general package. - -One fresh clean-context forward test must identify the applicable skill for representative repository inspection, implementation delivery, design, review, publication, and toolkit-maintenance prompts. One adversarial correctness review must pass before commit. - -## Idempotence and Recovery - -Skill installation and validation are safe to repeat. The installer owns only its recorded skill copies. If validation fails, correct the branch candidate and rerun the focused check. - -## Artifacts and Notes - -Store detailed results in `.agent/test-results/cpk-027-lifecycle-skills.md`. Do not stage that record. - -## Interfaces and Dependencies - -Use the existing skill loader and installer. Add no dependency, runtime service, or custom router. - -Revision note: Created the plan from the accepted lifecycle-skill design. - -Revision note: Recorded the completed rule and installer migration. - -Revision note: Recorded successful validation and lifecycle-skill trigger testing. - -Revision note: Recorded the clean full review and completed roadmap transition. diff --git a/docs/plans/cpk-028-phase-scoped-minimalism.md b/docs/plans/cpk-028-phase-scoped-minimalism.md deleted file mode 100644 index 026df51..0000000 --- a/docs/plans/cpk-028-phase-scoped-minimalism.md +++ /dev/null @@ -1,100 +0,0 @@ -# Scope minimalism by lifecycle phase - -This ExecPlan is a living document. The sections `Progress`, `Surprises & Discoveries`, `Decision Log`, and `Outcomes & Retrospective` must remain current. Maintain this document under `.agent/PLANS.md`. - -## Purpose / Big Picture - -Codex must not use implementation minimalism to shrink requirements, scenario discovery, test scope, or correctness review. After this change, lifecycle rules select normal mode for those phases and Ponytail full only while writing tests, production changes, or accepted review corrections. A scenario-to-check mapping makes every retained runtime transition auditable before implementation and review. - -## Progress - -- [x] (2026-08-16 16:15Z) Activated CPK-028 on branch `cpk-028-phase-scoped-minimalism` and recorded the accepted design. -- [x] (2026-08-16 16:15Z) Fixed the required checks and scenario oracles before implementation. -- [x] (2026-08-16 16:20Z) Added the canonical implementation-mode owner and routed lifecycle skills to it. -- [x] (2026-08-16 16:20Z) Added transition-closed Scenario Proof mapping to planning and review. -- [x] (2026-08-16 16:24Z) Updated focused tests, user documentation, version 0.15.0, and the manifest. -- [x] (2026-08-16 16:30Z) Passed validation, forward testing, and the first full correctness review with no findings; prepared the reviewed candidate for commit. -- [ ] Install the exact commit live and publish version 0.15.0. - -## Surprises & Discoveries - -- Observation: The cleaner Meridian run was not a controlled Ponytail A/B test because higher-priority rules enabled Ponytail during implementation. - Evidence: `worktree3.md` records that the session rules forced Ponytail despite the task prompt. -- Observation: The remaining Meridian defect crossed scenarios that were checked separately. - Evidence: The checks covered an older success after a newer assignment and retry classification, but not `A applying -> B accepted -> A retry -> B completes` as one production-path scenario. - -## Decision Log - -- Decision: Keep upstream Ponytail unchanged and select its documented `normal mode` at lifecycle boundaries. - Rationale: A future third-party updater owns upstream components. Toolkit policy must compose with that interface, not fork it. - Date/Author: 2026-08-16 / Codex and user. -- Decision: Make Delivery Lifecycle the sole owner of phase mode selection. - Rationale: One shared phase transition rule prevents planning, implementation, and review skills from defining competing defaults. - Date/Author: 2026-08-16 / Codex and user. -- Decision: Require transition-closed scenario mappings before implementation and concrete results before review. - Rationale: Separate component tests and aggregate suite counts cannot prove a composed state transition. - Date/Author: 2026-08-16 / Codex and user. -- Decision: Release this feature as version 0.15.0. - Rationale: Phase-scoped lifecycle behavior is a new toolkit capability, so the pre-1.0 minor digit increments from committed version 0.14.0. - Date/Author: 2026-08-16 / Codex and user. - -## Outcomes & Retrospective - -Version 0.15.0 passed all validation and the first full correctness review without findings. One canonical owner now selects minimalism by lifecycle phase. Transition-closed Scenario Proof mappings connect each retained path to an oracle and runnable result. Upstream Ponytail remains unchanged. No residual risk remains. - -## Context and Orientation - -`assets/skills/delivery-lifecycle/` owns shared task transitions. `assets/skills/design-preflight/` derives supported runtime scenarios. `assets/skills/adversarial-review/` reviews a staged candidate. `assets/AGENTS.block.md` routes agents to those owners. `tests/test_kit.py` verifies unique owners and installed content. `kit.py` contains the committed toolkit version. - -Ponytail is a separately maintained implementation-minimalism skill. Normal mode means the skill is disabled for the named phase. Full mode means its shortest-correct-implementation rules apply. A transition-closed scenario follows all supported events that can affect retained state until the required terminal result is observed. - -## Product Boundary - -Apply [Scope boundaries](../../assets/skills/design-preflight/references/scope-boundaries.md). The authoritative requirement is the accepted CPK-028 plan in this file. Delivery Lifecycle, Design Preflight, Research First, and Adversarial Review compose because this task changes their shared phase transitions. Upstream Ponytail is opaque and must not be changed. No third-party update mechanism is part of this task. - -## Scenario Proof - -Apply [Owner composition](../../assets/skills/design-preflight/references/owner-composition.md). This is toolkit policy, not product runtime code, so no runtime Cartesian scenario set is required. The following policy scenarios are the acceptance proof. - -| Scenario | Production path | Required oracle | Runnable test | Result | -| --- | --- | --- | --- | --- | -| Planning a non-trivial change | AGENTS -> Design Preflight -> Delivery Lifecycle mode owner | Normal mode remains active until required scenarios, oracles, and planned checks are accepted | `test_implementation_modes_are_phase_scoped` | Pass | -| Implementing an accepted plan | Delivery Lifecycle mode owner -> Ponytail | Ponytail full applies to test and production edits only after test scope is fixed | `test_implementation_modes_are_phase_scoped` | Pass | -| Correcting a review finding | Adversarial Review -> mode owner -> correction -> review | Correction uses implementation mode and the next read-only pass returns to normal mode | `test_implementation_modes_are_phase_scoped` | Pass | -| Retained state receives a later supported event | Design Preflight -> Owner Composition -> preflight card -> reviewer packet | One composed scenario follows the event sequence to a terminal oracle; component checks and suite counts cannot substitute | `test_scenario_proof_maps_transition_closed_checks` | Pass | - -## Plan of Work - -Create `assets/skills/delivery-lifecycle/references/implementation-modes.md` as the only detailed phase-mode owner. Route Delivery Lifecycle and the task-phase skills to it without copying its rules. Remove Research First's local instruction to apply Ponytail. Extend Owner Composition so a scenario set remains open while a supported later event can act on retained state without a terminal oracle. - -Update the preflight card and independent challenge schema with production path, oracle, and planned check fields. Require the coordinator to fill the actual runnable check and result before review. Update the reviewer packet and correctness lens to inspect that mapping. Add focused ownership and behavior assertions in `tests/test_kit.py`, then update the smallest authoritative user documents, version, and manifest. - -## Concrete Steps - -Work from `/home/mbeutler/Projects/codex-practical-kit`. Apply edits with `apply_patch`. Run `python -m unittest tests.test_kit`, the repository validation commands named in the README, and `quick_validate.py` for every changed skill. Generate `MANIFEST.sha256` only after documentation is final. Stage the complete candidate, record `git write-tree`, and run the required clean-context review workflow. Install that exact reviewed candidate with `./install.sh`, then require `./doctor.sh` to report version 0.15.0 and `Result: ready` before publication. - -## Validation and Acceptance - -`test_implementation_modes_are_phase_scoped` must fail if phase defaults are duplicated, planning enables Ponytail before test scope is fixed, an explicit user mode cannot override the default, or review corrections do not return to normal mode. `test_scenario_proof_maps_transition_closed_checks` must fail if the transition-closure rule, mapping columns, planned check, actual result, or reviewer verification is absent. The full test suite, skill validators, manifest check, installer, Doctor, and clean-context review must pass. - -The generic A/B validation prompt asks one fresh agent to plan a stateful change, select the planning and implementation modes, and map its proof. The transition case is `A retained -> B accepted -> A retry -> B terminal`; the accepted plan must require one composed production-path check whose oracle proves A cannot reappear or become eligible. - -Observed validation: one fresh agent selected normal mode for planning, mapped the complete `A applying -> B accepted -> A retry -> B completes` path to one runnable production-path check, rejected an aggregate suite pass, and selected Ponytail full for implementation. - -## Idempotence and Recovery - -Tests and validation commands are repeatable. The installer is designed for repeat use. If a required check, review, install, or publication gate fails, stop and report the exact result; do not invent recovery or publish an unreviewed tree. - -## Artifacts and Notes - -Store ignored review evidence in `.agent/test-results/cpk-028-phase-scoped-minimalism.md`. Do not stage that record. Preserve unrelated untracked workspace paths. - -## Interfaces and Dependencies - -Do not add dependencies or modify the upstream Ponytail skill. Use its existing exact `normal mode` interface and its default full implementation mode. Add one focused rule owner named `implementation-modes`; all other files route to it. - -Revision note (2026-08-16): Created the accepted CPK-028 execution plan and fixed its implementation checks before code changes. - -Revision note (2026-08-16): Recorded the implemented owners, passing checks, documentation, version, manifest, and generic forward-test result before review. - -Revision note (2026-08-16): Recorded the clean full review and completed roadmap transition. diff --git a/docs/plans/cpk-029-plan-mode-hook.md b/docs/plans/cpk-029-plan-mode-hook.md deleted file mode 100644 index 1cf91b8..0000000 --- a/docs/plans/cpk-029-plan-mode-hook.md +++ /dev/null @@ -1,92 +0,0 @@ -# Activate normal mode for Plan-mode prompts - -This ExecPlan is a living document. Maintain it under `.agent/PLANS.md`. - -## Purpose / Big Picture - -When a user selects Codex Plan mode, the toolkit must select Ponytail normal mode before planning begins. The user does not need to type a separate mode command. Prompts in other Codex modes must not change the current Ponytail mode. - -## Progress - -- [x] (2026-08-16 16:41Z) Created branch `cpk-029-plan-mode-hook` from `main` commit `ab27741605695df5ef65346d83177143fb5c79d8`. -- [x] (2026-08-16 16:41Z) Completed research and an independent Design Preflight challenge. -- [x] (2026-08-16 16:41Z) Fixed the runtime scenarios, oracles, and planned checks before implementation. -- [x] (2026-08-16 16:48Z) Implemented the managed prompt hook and passed all 33 tests, Python compilation, shell syntax, and diff checks. -- [x] (2026-08-16 16:48Z) Finalized current hook and implementation-mode documentation. -- [x] (2026-08-16 16:56Z) Corrected the pass-1 duplicate-handler finding and added a focused reinstall check. -- [x] (2026-08-16 17:03Z) Passed the fix-delta review and final coherence review with no findings. -- [ ] Install the exact commit live and publish version 0.15.1. - -## Surprises & Discoveries - -- Observation: Codex has no event that runs when the user selects Plan mode. - Evidence: The current hook events include `UserPromptSubmit`, and that event receives `permission_mode: "plan"` before prompt dispatch. -- Observation: A managed block and later exact unmarked handlers can coexist before reinstall. - Evidence: Full review pass 1 found that the missing-event check left both copies active. - -## Decision Log - -- Decision: Use the existing hook script for `SessionStart` and `UserPromptSubmit`. - Rationale: Event dispatch in one installed script is smaller than a second script and keeps one runtime owner. - Date/Author: 2026-08-16 / Codex. -- Decision: Emit the exact text `normal mode` only for Plan-mode prompt events. - Rationale: Ponytail documents this exact command. Plain hook output becomes developer context before Codex receives the prompt. - Date/Author: 2026-08-16 / Codex. -- Decision: Release version 0.15.1. - Rationale: This patch corrects the incomplete CPK-028 phase transition. It does not add a separate product feature. - Date/Author: 2026-08-16 / Codex. - -## Outcomes & Retrospective - -Version 0.15.1 passes all 34 tests and final coherence review. Plan-mode prompts select normal mode before dispatch. Non-Plan prompts remain unchanged. Installation reconciles partial and duplicate hook configurations without changing unrelated hooks. No residual risk remains. - -## Context and Orientation - -`kit.py` installs one managed hook block in the user Codex `config.toml`. `assets/hooks/session_start.py` is the installed hook command. `tests/test_kit.py` checks hook installation and behavior. `assets/skills/delivery-lifecycle/references/implementation-modes.md` remains the sole policy owner. - -Codex calls `UserPromptSubmit` before it sends a prompt. The input contains `permission_mode`. The value is `plan` in Plan mode. Text on standard output becomes developer context for that prompt. - -## Product Boundary - -Apply [Scope boundaries](../../assets/skills/design-preflight/references/scope-boundaries.md). Hook configuration, hook runtime behavior, diagnostics, and the implementation-mode owner compose. Upstream Ponytail is opaque. Malformed external configuration, malformed hook input, I/O faults, concurrency, and upstream mode changes are excluded. - -## Scenario Proof - -| Scenario | Production path | Required oracle | Runnable test or command | Result | -| --- | --- | --- | --- | --- | -| Submit a Plan-mode prompt | `UserPromptSubmit` configuration -> installed hook -> Codex developer context | The hook exits successfully and emits exact `normal mode` context before prompt dispatch | `test_plan_mode_prompt_selects_normal_mode` | Pass | -| Submit a non-Plan prompt | `UserPromptSubmit` configuration -> installed hook -> no returned context | The hook exits successfully and emits no mode-changing output | `test_plan_mode_prompt_selects_normal_mode` | Pass | -| Start or resume a session | `SessionStart` configuration -> installed hook -> Codex developer context | The existing router announcement is unchanged | `test_session_start_still_announces_router` | Pass | -| Install, reinstall, and remove hooks | `install_core` -> managed block -> Doctor -> `uninstall_hooks` | Each required event exists once, unrelated hooks remain, and uninstall removes only the managed block | existing installer round-trip test, extended for both events | Pass | - -## Plan of Work - -Add `UserPromptSubmit` to the managed hook block. Make the existing script read the event input. Emit `normal mode` for Plan-mode prompt events, emit nothing for other prompt modes, and preserve the Session Start response. Make hook detection require both event handlers. Extend the focused installer and runtime checks. Update the current hook documentation, version, roadmap, and manifest. - -## Concrete Steps - -Work from `/home/mbeutler/Projects/codex-practical-kit` on branch `cpk-029-plan-mode-hook`. Run `./run-tests.sh`, Python and shell syntax checks, `git diff --check`, and `sha256sum --check MANIFEST.sha256`. Stage the complete candidate and run Adversarial Review. After a clean review, commit the candidate. Install that exact commit with `./install.sh`. Require `./doctor.sh` to report version 0.15.1 and `Result: ready`. Then publish through the repository publication mode. - -## Validation and Acceptance - -The focused runtime check must invoke the configured command with real hook JSON. Plan mode must produce `normal mode`. A supported non-Plan mode must produce no output. Session Start must still produce the router announcement. Parsed configuration must contain one handler for each managed event after repeated installation. - -## Idempotence and Recovery - -Installation and validation are repeatable. If one operation fails, stop and report the error. Do not repair external configuration or publish an unreviewed candidate. - -## Artifacts and Notes - -Store detailed evidence in ignored file `.agent/test-results/cpk-029-plan-mode-hook.md`. Never stage it. - -## Interfaces and Dependencies - -Use Python standard-library JSON parsing and the current Codex hook interface. Add no dependency and no upstream Ponytail change. - -Revision note (2026-08-16): Created the accepted plan with transition-closed checks before implementation. - -Revision note (2026-08-16): Recorded the completed implementation, scenario results, documentation, and validation before review. - -Revision note (2026-08-16): Recorded and corrected the pass-1 duplicate-handler finding. - -Revision note (2026-08-16): Recorded clean delta and coherence reviews and the completed roadmap transition. diff --git a/docs/plans/cpk-030-repowise-index-routing.md b/docs/plans/cpk-030-repowise-index-routing.md deleted file mode 100644 index 37a7a3a..0000000 --- a/docs/plans/cpk-030-repowise-index-routing.md +++ /dev/null @@ -1,123 +0,0 @@ -# Make RepoWise index-first and self-refreshing - -This ExecPlan is a living document. Maintain it according to `.agent/PLANS.md`. - -## Purpose / Big Picture - -Codex must use RepoWise as a code index, not only as a weak natural-language search service. Exact identifiers must resolve to verified source without broad filesystem exploration. RepoWise must also catch up committed work before MCP serves queries and index active working-tree saves through its native watcher. No LLM provider is required. A provider configured by the user remains useful for conceptual questions. - -## Progress - -- [x] (2026-08-16 18:01Z) Created branch `cpk-030-repowise-index-routing` from `main` at `840a97a5586e6c03f9501e3280f5973075177e60`. -- [x] (2026-08-16 18:01Z) Completed Design Preflight and current RepoWise 0.41.0 research. -- [x] (2026-08-16 19:18Z) Implemented index-first routing, startup catch-up, active-session working-tree updates, and watcher cleanup. -- [x] (2026-08-16 19:42Z) Validated all retained scenarios, completed 37 tests, finalized user documentation, and regenerated the manifest. -- [x] (2026-08-16 20:07Z) Completed adversarial review and live installation. Prepared the local checkpoint commit. - -## Surprises & Discoveries - -- Observation: `get_answer` without a provider returned `degraded: no-llm-provider`, low confidence, and generic fallback targets. An exact `search_codebase(mode="symbol")` lookup returned `kit.py::install_hooks`, and `get_symbol` returned its verified live body without a filesystem read. -- Observation: The post-commit hook fired for two commits, but its background child disappeared under Codex process supervision before RepoWise advanced. A detached update advanced the index from `0045b6f` to `840a97a` in 2.3 seconds. -- Observation: RepoWise 0.41.0 provides `watch --index-only`. It batches eligible working-tree changes after a two-second debounce and avoids model calls. -- Observation: The unmodified RepoWise 0.41.0 watcher treats file-open and file-close notifications as changes. Its update reads source files, so one edit starts an endless update loop. RepoWise 0.43.0 has the same behavior. -- Observation: Ignoring only `opened`, `closed`, and `closed_no_write` notifications keeps RepoWise's native watcher stable. One edit produced one update and no later update during an eight-second observation. -- Observation: RepoWise `update` exits with status 1 before the first commit, even after a successful empty-repository `init`. Startup now skips catch-up when `HEAD` does not exist. - -## Decision Log - -- Decision: Keep all query-routing rules in `assets/skills/repository-knowledge/SKILL.md`. - Rationale: It is the existing unique `repository-knowledge` owner. AGENTS remains a router. - Date/Author: 2026-08-16 / Codex and user. -- Decision: Use model synthesis only for conceptual how/why questions. - Rationale: Exact symbols and paths are cheaper and more reliable through deterministic selectors. - Date/Author: 2026-08-16 / user. -- Decision: Compose synchronous startup catch-up, native active-session watch, and the existing post-commit hook. - Rationale: RepoWise already supplies each primitive. The launcher applies one pinned compatibility filter before it invokes the native watcher. - Date/Author: 2026-08-16 / Codex and user. -- Decision: Suppress watcher read notifications through RepoWise's Python launcher. - Rationale: RepoWise's update reads trigger its own watcher. The filter removes the false wake and preserves native debounce and working-tree indexing. - Date/Author: 2026-08-16 / Codex. -- Decision: Target version `0.16.0`. - Rationale: Query corrections are fixes, but automatic uncommitted working-tree monitoring is a new supported capability before 1.0.0. - Date/Author: 2026-08-16 / Codex. - -## Outcomes & Retrospective - -Version 0.16.0 routes exact lookups through RepoWise's symbol index and keeps working-tree edits indexed without model calls. The pinned watcher needs one compatibility filter for read-only filesystem events. Runtime smoke checks proved that initial and later edits each caused one update and then settled. Review pass 1 exposed a no-`HEAD` startup defect. The fix delta and final coherence review were clean. The full 38-test suite passes. Live installation and both Doctor checks reported `Result: ready`. - -## Context and Orientation - -`kit.py:repowise_bootstrap()` renders the required user-level MCP command. It initializes an absent index, installs RepoWise's Git hook, and starts MCP. `assets/skills/repository-knowledge/SKILL.md` is the sole owner of agent lookup behavior. `tests/test_kit.py` covers bootstrap behavior and unique rule ownership. `docs/REPOWISE.md` owns user-visible RepoWise behavior. - -The task uses one normal branch because it has one writable implementation stream. Preserve the existing untracked `.claude/`, `.codex/`, `.mcp.json`, `.repowise/`, and `.vscode/` paths. - -## Product Boundary - -Apply [Scope boundaries](../../assets/skills/design-preflight/references/scope-boundaries.md). The authoritative product sources are `docs/REPOWISE.md` and `docs/WHY-THIS-SHAPE.md`. - -Repository lookup instructions and the managed MCP bootstrap are `composes`. RepoWise's watcher entry point is also `composes` because the launcher filters its event input. The AGENTS router, remaining RepoWise 0.41.0 behavior, provider configuration, and repository opt-out behavior are `opaque`. No deferred owner is promoted. - -The supported model has one personal user and one Codex writer on a normal local Git filesystem. Exclude I/O faults, permissions, links, retries, recovery, arbitrary concurrency, submodules, new dependencies, provider credentials, custom watchers, and RepoWise database changes. - -## Scenario Proof - -Apply [Owner composition](../../assets/skills/design-preflight/references/owner-composition.md) and [Full-set results](../../assets/skills/design-preflight/references/full-set-results.md). - -| Scenario | Production path | Required oracle | Runnable test or command | Result | -| --- | --- | --- | --- | --- | -| Exact identifier without provider | repository skill → symbol search → `get_symbol` | Exact verified body; no preceding broad native search | `repowise search repowise_watch_command --mode symbol --format json`, then `repowise symbol kit.py::repowise_watch_command --format json` | Exact index match and verified source body | -| Known path or relationship | repository skill → `get_context` → needed indexed block | Requested target and relationship resolve before source confirmation | `repowise context kit.py --format json` | Indexed file card returned without broad search | -| Concept question without provider | `get_answer` → degraded session state → indexed candidates | At most one degraded answer call in the session | `test_repowise_routes_indexed_queries` | Owner contract passed | -| Concept question with provider | `get_answer` → confidence/citations/symbol bodies | Provider result remains usable without becoming required | `test_repowise_routes_indexed_queries` | Owner contract passed; no provider was installed | -| Committed index behind at startup | bootstrap → index-only update → MCP | Update completes before MCP starts | `test_bootstrap_initializes_once_and_always_installs_hook` | Passed | -| Rapid eligible saves | watcher filter → native debounce → working-tree update | Every final changed path reaches the index with no model call | Temporary-repository watcher smoke test | One update completed and the watcher settled | -| Later save after first update | watcher releases update gate → later update | Later symbol state reaches the index | Live repository watcher smoke test | A later test edit caused one update; the watcher settled again | -| MCP exit | MCP terminal event → watcher cleanup | No managed watcher remains | `test_bootstrap_initializes_once_and_always_installs_hook` | Passed; both watcher PIDs were gone | -| Empty or non-Git workspace | existing bootstrap selector | Empty folder initializes; non-empty non-Git folder stays unchanged | Real empty-folder bootstrap plus `test_bootstrap_initializes_only_empty_non_git_directory` | Real bootstrap exited 0 with Git, index, watcher, and MCP startup; test passed | - -## Plan of Work - -First expand the repository-knowledge owner with deterministic query-shape routing, session-scoped no-provider handling, bounded fallback, ambiguity handling, and verified-source behavior. - -Then extend `repowise_bootstrap()` to run an index-only update before MCP. Start RepoWise's watcher through its pinned Python interpreter and ignore read-only filesystem notifications. Redirect non-protocol output, run MCP in the foreground, and clean up the watcher when MCP exits. Keep RepoWise's hook installation. Make eager repository setup catch an existing index up once. - -Add focused bootstrap and rule-owner tests. Update the RepoWise documentation, version owners, roadmap, and checksum manifest after behavior is final. - -## Concrete Steps - -Work from `/home/mbeutler/Projects/codex-practical-kit` on branch `cpk-030-repowise-index-routing`. - -Run focused tests while editing, then run: - - ./run-tests.sh - sh -n doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh - git diff --check - sha256sum --check MANIFEST.sha256 - -Store detailed results in `.agent/test-results/cpk-030-repowise-index-routing.md`. Do not stage that file. - -## Validation and Acceptance - -The new bootstrap test must fail if update does not precede MCP, automatic paths omit `--index-only`, watcher output reaches MCP stdout, or the watcher remains after MCP exits. The routing test must fail if exact symbol lookup, session-scoped degraded handling, optional conceptual synthesis, bounded native fallback, or verified-source behavior disappears. - -A real temporary repository must prove that rapid eligible saves and a later separate save become queryable through RepoWise. The watcher must settle after each update. A fresh no-provider Codex trace must resolve one named function through the index without broad native exploration. - -After clean review, run `./install.sh`, `./doctor.sh`, and `./doctor.sh --repo .` from the reviewed candidate. Require `Result: ready`. - -## Idempotence and Recovery - -Installation, setup, startup catch-up, hook installation, and watcher startup are repeatable. RepoWise owns update serialization. The compatibility filter is pinned to RepoWise 0.41.0 internals. Attempt each operation once. On failure, stop and report it. Do not add retries or recovery. - -## Artifacts and Notes - -RepoWise's default watcher debounce is the accepted change threshold. Automatic watch updates remain index-only even when a user later configures an LLM provider. - -## Interfaces and Dependencies - -No new public command or dependency is added. The generated MCP command gains startup update, a watcher event filter, and watcher lifecycle behavior. RepoWise remains pinned at 0.41.0. Source version becomes 0.16.0. - -Revision note (2026-08-16): The plan now records the watcher read-event loop found by the runtime smoke test and the minimal compatibility filter that removes it. - -Revision note (2026-08-16): Review pass 1 found that RepoWise cannot update a repository before its first commit. The fix skips startup catch-up until `HEAD` exists and adds real and automated checks. - -Revision note (2026-08-16): Fix-delta and final coherence reviews were clean. The reviewed candidate passed live installation and both Doctor checks. diff --git a/docs/plans/cpk-031-tracked-state-freeze.md b/docs/plans/cpk-031-tracked-state-freeze.md deleted file mode 100644 index c0e1026..0000000 --- a/docs/plans/cpk-031-tracked-state-freeze.md +++ /dev/null @@ -1,96 +0,0 @@ -# Freeze tracked task status before delivery - -This ExecPlan is a living document. Maintain it under `.agent/PLANS.md`. - -## Purpose / Big Picture - -Tracked task records must stop changing before delivery starts. The roadmap must describe durable product state. The ExecPlan must describe implementation, validation, and review. Git and GitHub must own later delivery status. - -## Progress - -- [x] (2026-08-16 22:08Z) Inspected the roadmap, ExecPlan, review-closure, delivery, publication, and rule-owner contracts. -- [x] (2026-08-16 22:08Z) Accepted one tracked-state freeze for all tracked task records. -- [x] (2026-08-16 22:08Z) Created branch `cpk-031-tracked-state-freeze` from CPK-030 commit `81450545d9ca`. -- [x] (2026-08-16 22:12Z) Corrected the canonical owners and added one focused regression check. -- [x] (2026-08-16 22:12Z) Validated version `0.16.1`, documentation, tests, syntax, diff, and manifest integrity. -- [x] (2026-08-16 22:22Z) Completed adversarial review and recorded the final durable outcome. - -## Surprises & Discoveries - -- Observation: Review Closure permits a tracked `publication status` update after clean review. - Evidence: `assets/skills/adversarial-review/references/review-closure.md` lists it as one of five closure updates. -- Observation: Roadmap Maintainer requires the transient text `validation is complete and review is pending`. - Evidence: `assets/skills/roadmap-maintainer/SKILL.md` requires this text before review. -- Observation: Existing ExecPlans contain delivery checkboxes and publication-status prose. - Evidence: The current `.agent/PLANS.md` does not bound `Progress` at review closure. -- Observation: `.agent/PLANS.md` is installed in two locations with different relative-path roots. - Evidence: Review pass 1 found that its new repository-relative route breaks in `$CODEX_HOME/PLANS.md`. - -## Decision Log - -- Decision: Delivery Lifecycle owns the general tracked-state freeze. - Rationale: It already owns the boundary between implementation, review, commit, and delivery. - Date/Author: 2026-08-16 / Codex -- Decision: Keep roadmap and ExecPlan rules specific to their content. - Rationale: This keeps one general rule owner and prevents duplicate authority. - Date/Author: 2026-08-16 / Codex -- Decision: Use version `0.16.1`. - Rationale: This task corrects committed workflow behavior after version `0.16.0`. - Date/Author: 2026-08-16 / Codex -- Decision: Route Delivery Lifecycle through AGENTS instead of `.agent/PLANS.md`. - Rationale: AGENTS already owns skill routing and uses the correct installed skill path. - Date/Author: 2026-08-16 / Codex - -## Outcomes & Retrospective - -The tracked-state owners now agree on one pre-delivery freeze. All 39 tests pass. Review pass 1 found one broken installed link. Its focused correction passed delta review and final coherence review. No residual risk remains. No separate user manual change is necessary because the focused skills own this behavior. - -## Context and Orientation - -`assets/skills/delivery-lifecycle/references/delivery-lifecycle.md` owns the shared task sequence. Roadmap Maintainer owns durable task states. `.agent/PLANS.md` owns ExecPlan content. Review Closure owns permitted final record updates. Publication owns Git and GitHub delivery actions. `tests/test_kit.py` protects these rule contracts. - -The base branch is `cpk-030-repowise-index-routing`. The base commit is `81450545d9ca335c0744f9f8bf79efc097873783`. The task branch is `cpk-031-tracked-state-freeze`. The isolation form is a normal stacked branch. - -## Product Boundary - -The product source is the accepted CPK-031 plan and the current managed lifecycle skills. This task composes the live delivery, roadmap, ExecPlan, review-closure, and publication owners. Completed ExecPlans and roadmap history are records. They are not live rule owners and remain unchanged. - -This task changes agent instructions. It does not change executable runtime behavior. Design Preflight does not need an independent challenge because ownership and scope are clear. - -## Scenario Proof - -This task has no runtime Scenario Proof. The focused rule check is the required oracle. - -## Plan of Work - -Add one general freeze rule to Delivery Lifecycle. Remove transient review state from Roadmap Maintainer. Bound ExecPlan progress at final review closure. Remove publication status from Review Closure. Make Publication consume the frozen tracked candidate without writing delivery results to tracked files. - -Add one focused test that reads these live owners. The test must reject duplicate freeze ownership, transient roadmap readiness, future delivery actions in ExecPlan progress, and tracked publication-result updates. - -Update the source version to `0.16.1`. Update the manifest after all tracked files reach their final content. - -## Concrete Steps - -Work in `/home/mbeutler/Projects/codex-practical-kit` on branch `cpk-031-tracked-state-freeze`. - -Run `./run-tests.sh`, Python syntax checks, shell syntax checks, `git diff --check`, and `sha256sum --check MANIFEST.sha256`. Record detailed results in `.agent/test-results/cpk-031-tracked-state-freeze.md`. Never stage that file. - -Stage the complete candidate and run Adversarial Review. After a clean review, apply only Review Closure updates. Then freeze the tracked candidate before its task commit. - -## Validation and Acceptance - -The focused check must fail against the old rules and pass against the corrected owners. The full suite and manifest checks must pass. After the task commit, `./install.sh` and `./doctor.sh` must report version `0.16.1` and `Result: ready`. These results must not change a tracked file. - -## Idempotence and Recovery - -The tests, installer, and Doctor are repeatable. If a required command fails, stop and report the exact error. Do not write delivery progress to a tracked document. - -## Artifacts and Notes - -Store detailed command and review evidence only in `.agent/test-results/cpk-031-tracked-state-freeze.md`. - -## Interfaces and Dependencies - -There is no new runtime interface or dependency. The public agent contract gains one tracked-state freeze before delivery. - -Revision note (2026-08-16): Created from the accepted CPK-031 plan and the inspected live rule conflicts. Finalized after implementation, validation, one corrected review finding, and clean coherence review. diff --git a/docs/plans/cpk-032-default-mode-preflight.md b/docs/plans/cpk-032-default-mode-preflight.md deleted file mode 100644 index a1f3ec8..0000000 --- a/docs/plans/cpk-032-default-mode-preflight.md +++ /dev/null @@ -1,115 +0,0 @@ -# Invoke planning and RepoWise throughout applicable work - -This ExecPlan is a living document until review closure. Maintain it under `.agent/PLANS.md`. - -## Purpose / Big Picture - -Non-trivial runtime work must use Design Preflight before code even when the user does not request Plan Mode. Its fresh planning challenger uses xhigh reasoning, including for qualifying review corrections, before the main thread resumes its configured implementation effort. Each new repository discovery question must use RepoWise throughout implementation and review corrections. Initial planning and repository orientation do not satisfy later questions. - -## Progress - -- [x] (2026-08-17 06:32Z) Reviewed the 063F diagnostic and the current lifecycle, preflight, review, and repository-knowledge owners. -- [x] (2026-08-17 06:32Z) Created branch `cpk-032-default-mode-preflight` from `main` commit `935e592e61e1`. -- [x] (2026-08-17 07:41Z) Added focused owner-contract checks and captured the expected pre-change failure. -- [x] (2026-08-17 07:46Z) Corrected automatic preflight invocation, correction routing, reasoning phases, Scenario Proof, and continuous RepoWise routing. -- [x] (2026-08-17 07:55Z) Completed both clean-context forward tests, focused skill validation, and the 40-test suite. -- [x] (2026-08-17 08:18Z) Resolved two P2 entry-gate findings; the correction delta and final coherence review were clean. - -## Surprises & Discoveries - -- Observation: Design Preflight describes applicable work but does not state that implicit invocation applies outside UI Plan Mode. - Evidence: Its current metadata describes a non-trivial change without naming Default-mode implementation or review corrections. -- Observation: Repository Knowledge requires RepoWise before broad exploration but does not bind the rule to each later discovery question. - Evidence: Its current opening can be satisfied by one initial query. -- Observation: Owner Composition already covers retained states, reopening sources, terminal owners, and composed checks. - Evidence: Only unordered counterexample ordering and shared-signal cause discrimination are absent from the focused owner. -- Observation: Codex applies `plan_mode_reasoning_effort` only in Plan Mode, and hooks cannot change reasoning effort. - Evidence: The official configuration reference defines a Plan-mode-specific override and explicit subagent effort; the hook output contract contains no reasoning control. -- Observation: Review pass 1 found that the correction examples narrowed the shared entry gate and that a qualifying non-runtime correction could skip the challenger. - Evidence: The candidate used different correction criteria in its entry and challenge sections. -- Observation: A review finding does not by itself require Design Preflight. - Evidence: The user confirmed that a small correction with one proven owner and one direct check must keep the existing exception. - -## Decision Log - -- Decision: Keep automatic activation in skill metadata and lifecycle rules. - Rationale: Hooks cannot reliably classify task semantics, and Design Preflight can run in Default mode. - Date/Author: 2026-08-17 / Codex -- Decision: Keep query routing in Repository Knowledge. - Rationale: It is the existing single owner for RepoWise use. - Date/Author: 2026-08-17 / Codex -- Decision: Use an xhigh fresh planning challenger and keep implementation in the main thread's configured effort. - Rationale: This preserves the useful Plan-mode phase split without unsupported active-thread mutation or hook machinery. - Date/Author: 2026-08-17 / Codex -- Decision: Apply the same Design Preflight entry gate and small-change exception to accepted corrections. - Rationale: Automatic correction planning must not force full preflight for simple review rework. - Date/Author: 2026-08-17 / Codex -- Decision: Use version `0.17.0`. - Rationale: Automatic reasoning-effort phase selection outside Plan Mode is a new toolkit capability after committed version `0.16.1`. - Date/Author: 2026-08-17 / Codex - -## Outcomes & Retrospective - -Version `0.17.0` now applies Design Preflight outside Plan Mode when its normal entry gate matches. The same gate and small-change exception apply to accepted corrections. Qualifying corrections use a fresh xhigh planning challenger before the main thread resumes its configured implementation effort. RepoWise now owns every new repository lookup throughout a task, and Owner Composition covers outcome-changing order and shared-signal causes without exhaustive permutations. - -Both clean-context forward tests selected the intended skills without explicit names. All 40 tests, skill validation, syntax checks, diff checks, and manifest checks passed. Full review found two P2 gate defects. Their correction delta and the final coherence pass were clean. Publication was not authorized. - -## Context and Orientation - -Design Preflight owns applicability and Scenario Proof. Delivery Lifecycle owns the transition into implementation and accepted corrections. Adversarial Review owns correction review. Repository Knowledge owns RepoWise query selection. Owner Composition owns retained-state and event-path composition. `tests/test_kit.py` protects these contracts. - -The base branch is `main`. The base commit is `935e592e61e1e32caba1dc91970ef560441926d1`. The task branch is `cpk-032-default-mode-preflight`. The isolation form is one normal branch. - -## Product Boundary - -The authoritative sources are the accepted CPK-032 plan and `/home/mbeutler/Downloads/063F-triage.md`. The live lifecycle, preflight, owner-composition, review, and repository-knowledge owners compose. RepoWise runtime, watcher behavior, provider configuration, hooks, Ponytail, and completed records are opaque. - -The supported model has one user and one Codex writer on a normal local Git filesystem. Exclude I/O faults, permissions, concurrency, interruption, retries, recovery, submodules, provider errors, new dependencies, and hook-based semantic classification. - -## Scenario Proof - -This task changes agent instructions, not executable product runtime. The focused owner checks and clean-context forward tests are the acceptance proof. A planning challenger is not required because ownership and scope are clear. - -## Plan of Work - -First add a focused test that fails unless Default-mode implementation and accepted corrections apply Design Preflight through one lifecycle owner. Extend the same test surface for unordered event counterexamples and shared-signal causes. - -Then update Design Preflight metadata, Delivery Lifecycle timing, Adversarial Review correction routing, Implementation Modes reasoning phases, and Owner Composition. Update Repository Knowledge so every new discovery question uses RepoWise. Route Design Preflight and Delivery Lifecycle to that owner without copying its query rules. - -Run two clean-context forward tests with raw implementation and correction prompts. Do not name Design Preflight or Repository Knowledge in those prompts. Require planning and indexed discovery before code. - -Update source version `0.17.0`, focused RepoWise documentation, and the checksum manifest after content is final. - -## Concrete Steps - -Work in `/home/mbeutler/Projects/codex-practical-kit` on branch `cpk-032-default-mode-preflight`. - -Run `./run-tests.sh`, skill validation, Python and shell syntax checks, `git diff --check`, and `sha256sum --check MANIFEST.sha256`. Store detailed results in ignored `.agent/test-results/cpk-032-default-mode-preflight.md`. - -Stage the complete candidate and run Adversarial Review. Apply only Review Closure updates after the final clean result. Freeze all tracked records before the task commit. - -## Validation and Acceptance - -The focused contract must fail against the old rules and pass after correction. The two forward tests must select planning, xhigh challenge reasoning, the configured implementation effort, and RepoWise without explicit skill names. The full suite and manifest checks must pass. After commit, install the exact candidate and require Doctor version `0.17.0` with `Result: ready`. - -## Idempotence and Recovery - -The tests, skill validator, installer, and Doctor are repeatable. If a required operation fails, stop and report the exact error. Do not add retries or speculative recovery. - -## Artifacts and Notes - -Keep detailed test and review evidence only in the ignored task result. - -The first forward test selected automatic preflight and task-long RepoWise lookup routing for a new Default-mode implementation. The second selected a fresh xhigh correction challenger, passed it the accepted finding without a preferred fix, and returned implementation to the main thread's configured effort. - -## Interfaces and Dependencies - -There is no new runtime interface or dependency. Design Preflight gains an implicit Default-mode trigger. Its fresh planning challenger uses xhigh before the main thread resumes its configured effort. Repository Knowledge gains task-long query routing. - -Revision note (2026-08-17): Created from the accepted plan, 063F diagnostic, and inspected live owner contracts. - -Revision note (2026-08-17): Added the accepted automatic xhigh planning phase for qualifying review corrections and changed the feature version to `0.17.0`. - -Revision note (2026-08-17): Review pass 1 corrected the accepted-correction entry and challenge gates while preserving the small-change exception. - -Revision note (2026-08-17): Closed after clean correction-delta and cumulative coherence reviews. diff --git a/docs/plans/cpk-033-repowise-route-persistence.md b/docs/plans/cpk-033-repowise-route-persistence.md deleted file mode 100644 index bba7eb1..0000000 --- a/docs/plans/cpk-033-repowise-route-persistence.md +++ /dev/null @@ -1,104 +0,0 @@ -# Keep RepoWise active for the full task - -This ExecPlan is a living document until review closure. Maintain it under the global `PLANS.md` rules. - -## Purpose / Big Picture - -Codex must continue to use RepoWise for each new repository lookup. A missing synthesis provider or an automatic compaction must not change that route. A fresh Codex session demonstrates the result by using indexed retrieval for separate questions without an explicit RepoWise request. - -## Progress - -- [x] (2026-08-17 08:32Z) Created branch `cpk-033-repowise-route-persistence` from reviewed commit `306577a53136`. -- [x] (2026-08-17 08:32Z) Completed Design Preflight and one independent planning challenge. -- [x] (2026-08-17 08:34Z) Added focused contract tests and captured the expected pre-change errors. -- [x] (2026-08-17 08:37Z) Corrected the owner, activation metadata, persistent router, and compact continuation. -- [x] (2026-08-17 08:39Z) Completed skill validation, focused checks, documentation, and the 40-test suite. -- [x] (2026-08-17 08:40Z) Completed a clean first full review and review closure. - -## Surprises & Discoveries - -- Observation: RepoWise remained available after Codex stopped using it. - Evidence: The Meridian transcript contains successful `search_codebase` and `get_symbol` calls before and after the drift. -- Observation: `no-llm-provider` has no route for later conceptual questions. - Evidence: The owner forbids another `get_answer` call but does not name an indexed replacement for the next question. -- Observation: The current long-lived Codex process uses an older plain RepoWise MCP command. - Evidence: New managed sessions use the bootstrap command and watcher. The existing process started before the current configuration. - -## Decision Log - -- Decision: Keep the complete lookup rule in `repository-knowledge`. - Rationale: This skill is the existing unique owner. AGENTS and the hook remain route-only surfaces. - Date/Author: 2026-08-17 / Codex -- Decision: Use official skill metadata, AGENTS routing, and `SessionStart` compact context together. - Rationale: Skill metadata declares the MCP dependency. AGENTS supplies the persistent default. The hook restores the route after compaction. - Date/Author: 2026-08-17 / Codex -- Decision: Do not block native commands or parse transcripts. - Rationale: OpenAI documents tool hooks as guardrails and does not define transcript format as a stable interface. - Date/Author: 2026-08-17 / Codex -- Decision: Use version `0.17.1`. - Rationale: This task corrects the published behavior of version `0.17.0`. - Date/Author: 2026-08-17 / Codex - -## Outcomes & Retrospective - -Version `0.17.1` keeps RepoWise active after a missing synthesis provider and automatic compaction. The skill has an explicit MCP dependency. Focused tests and all 40 repository tests pass. The first full correctness review was clean. - -## Context and Orientation - -`assets/skills/repository-knowledge/SKILL.md` owns repository lookup behavior. `assets/AGENTS.block.md` routes applicable work to skills. `assets/hooks/session_start.py` supplies Codex context after startup, resume, clear, or compaction. `tests/test_kit.py` protects installation and rule ownership. - -OpenAI documents progressive skill loading at `https://developers.openai.com/codex/skills`. It documents session instruction discovery at `https://developers.openai.com/codex/guides/agents-md`. It documents compact continuation context at `https://developers.openai.com/codex/hooks`. - -## Product Boundary - -The user requirement and the observed Meridian transcript are authoritative. Apply [Scope boundaries](../../assets/skills/design-preflight/references/scope-boundaries.md). The repository-knowledge skill owns lookup selection. The managed AGENTS block owns routing. The Session Start hook owns post-compaction context. RepoWise runtime, model-provider setup, and native-command enforcement are outside this task. - -The supported model has one user and one Codex writer in a normal local Git repository. A RepoWise index and MCP server are available. A synthesis provider is optional. Existing Codex sessions do not reload changed instructions or configuration. - -## Scenario Proof - -This task changes executable hook behavior and live agent instructions. It does not change product data or retained runtime state. - -Before compaction, a new lookup selects repository-knowledge and uses RepoWise. After `no-llm-provider`, the current candidate set remains usable. Each later conceptual question uses raw indexed search. Exact results use indexed context or symbol bodies. One stronger indexed query precedes focused native fallback. - -After compaction, `SessionStart` adds a route-only developer instruction before the immediate continuation. The next new repository lookup selects repository-knowledge again. A focused hook test provides the oracle. - -## Plan of Work - -First, add focused tests for skill metadata, the no-provider transition, the AGENTS route, and compact continuation. Record the expected pre-change errors. - -Then, update the repository-knowledge description and owner body. Add `agents/openai.yaml` with implicit invocation and the named RepoWise MCP dependency. Strengthen the AGENTS route without copying query rules. Add compact-specific context to the existing hook. - -Update the smallest RepoWise document with no-provider and restart behavior. Set the source version to `0.17.1`. Regenerate the manifest after all tracked content is final. - -## Concrete Steps - -Work in `/home/mbeutler/Projects/codex-practical-kit` on branch `cpk-033-repowise-route-persistence`. - -Run the focused contract tests before and after implementation. Then run `./run-tests.sh`, `git diff --check`, and `sha256sum --check MANIFEST.sha256`. Store detailed results in ignored file `.agent/test-results/cpk-033-repowise-route-persistence.md`. - -Stage the complete candidate and run Adversarial Review. After a clean result, apply review closure. Install the reviewed candidate with `./install.sh`. Then run `./doctor.sh --repo .` and a fresh Codex forward test. - -## Validation and Acceptance - -The focused tests must prove four outcomes. The skill declares the `repowise` MCP dependency. The no-provider state retains indexed routing. A compact event restores the skill route. The complete rule has one owner. - -The fresh forward test must ask separate conceptual and exact repository questions without naming RepoWise. After one `no-llm-provider` result, later conceptual questions must use `search_codebase`. Exact results must use `get_context` or `get_symbol`. Broad native search cannot occur before the bounded indexed fallback. - -The complete test suite and manifest checks must pass. Doctor must report version `0.17.1` and `Result: ready` from the reviewed candidate. - -## Idempotence and Recovery - -The tests, installer, and Doctor are repeatable. If a required operation fails, stop and report the exact error. Do not add retries or speculative recovery. - -## Artifacts and Notes - -Keep detailed validation and review evidence only in the ignored task result. Keep the tracked ExecPlan final before the task commit. - -## Interfaces and Dependencies - -The `repository-knowledge` skill gains standard `agents/openai.yaml` metadata. It names the existing `repowise` MCP server. The Session Start hook changes only its developer context for `source: compact`. No dependency or public command changes. - -Revision note (2026-08-17): Created from the accepted CPK-033 plan, official Codex documentation, transcript evidence, and the independent preflight challenge. - -Revision note (2026-08-17): Recorded the implemented behavior, validation results, and clean first full review. diff --git a/docs/plans/cpk-034-scenario-discrimination.md b/docs/plans/cpk-034-scenario-discrimination.md deleted file mode 100644 index 75708db..0000000 --- a/docs/plans/cpk-034-scenario-discrimination.md +++ /dev/null @@ -1,112 +0,0 @@ -# Require discriminating Scenario Proof checks - -This ExecPlan is a living document until review closure. Maintain it according to `.agent/PLANS.md`. - -## Purpose / Big Picture - -After this change, a Scenario Proof cannot rely on a test that exercises adjacent behavior while the named requirement remains false. Each retained scenario identifies the one meaningful distinction under test, a minimal contrast that exposes the nearby wrong meaning, and the terminal result that must differ. - -## Progress - -- [x] (2026-08-17 18:31Z) Accepted the CPK-034 plan and created the isolated task branch. -- [x] (2026-08-17 18:31Z) Activated CPK-034 as the sole roadmap task. -- [x] (2026-08-17 18:39Z) Added the focused rule owner and routed planning, review, and documentation surfaces to it. -- [x] (2026-08-17 18:44Z) Added the structural integration test and forward-tested the corrected raw source packet for all seven defect shapes. -- [x] (2026-08-17 18:46Z) Finalized linked documentation and passed skill validation, 41 tests, shell syntax, diff, and manifest checks. -- [x] (2026-08-17 18:50Z) Completed a clean full review of staged tree `888e94a0db41fc5feae331afb0c40980cbec8801` and closed the task. -- [x] (2026-08-18) Selected version `0.18.0` and completed a clean full review of the publication candidate. - -## Surprises & Discoveries - -- Observation: Current rules require a production path, terminal oracle, runnable check, and result. - Evidence: `assets/skills/design-preflight/references/preflight-card.md` contains those columns, but it does not require a contrast that makes the wrong meaning observable. -- Observation: The seven supplied defects share one test-design failure. - Evidence: Each cited test held the decisive values equal, omitted the decisive state, or stopped before the terminal consumer. -- Observation: The first forward-test packet misstated cross-line ownership and omitted the batch creation order. - Evidence: Its result permitted retargeting and split ingestion from scheduling. The corrected raw packet rejected cross-line edits and retained batch disposition as a contract gap. - -## Decision Log - -- Decision: Add one focused `scenario-discrimination` rule instead of seven workflow-specific rules. - Rationale: One contrast requirement covers identity, value, state, time, source, and event distinctions without a checklist. - Date/Author: 2026-08-17 / user and Codex -- Decision: Require a named discriminator and contrast, but do not require mutation-testing software or MC/DC metrics. - Rationale: A small proof obligation detects the observed gap without adding dependencies or exhaustive combinations. - Date/Author: 2026-08-17 / Codex -- Decision: Publish as version `0.18.0` through direct integration. - Rationale: CPK-034 adds a feature before 1.0.0. The repository has no CI workflows, so PR mode is off. - Date/Author: 2026-08-18 / Codex - -## Outcomes & Retrospective - -Implementation, forward testing, documentation, validation, and review are complete. The clean reviewer reported no findings. - -## Context and Orientation - -The task branch is `cpk-034-scenario-discrimination`. Its base branch is `main`, and its base commit is `e1d8ac887267590a763e733106121f79c927d121`. - -`assets/skills/design-preflight/SKILL.md` owns the preflight procedure. Its preflight card and challenger result define the Scenario Proof interface. Adversarial Review consumes the accepted mapping. `tests/test_kit.py` protects unique rule ownership and complete routing. - -A discriminator is the one identity, value, state, time, source, or event whose documented meaning a scenario proves. A contrast is the smallest paired input or seeded state that makes the required and nearby wrong meanings produce different terminal results. - -## Product Boundary - -Apply [Scope boundaries](../../assets/skills/design-preflight/references/scope-boundaries.md). The toolkit rule surfaces are `composes`. Installed copies and tenant project code are `opaque`. Actual mutation tooling, coverage metrics, exhaustive combinations, and seven workflow-specific rules are excluded. - -The supported model has one coordinator planning supported repository behavior. The project controls the preflight schema, rule routes, tests, and installed skill content. The supplied first-pass diagnostic reproduces the wrong proof result without environmental faults. The accepted plan defines the required result. - -## Scenario Proof - -This task changes a static planning interface, not product runtime behavior. The runtime Scenario Proof entry gate does not apply to this toolkit implementation itself. - -The rule-owner check must prove that one authoritative file owns scenario discrimination and every live consumer links to it. The schema check must prove that a retained scenario names its discriminator, contrast, production path, terminal oracle, runnable check, and result. The forward check must apply the same general rule to all seven supplied defect shapes without adding shape-specific live instructions. - -## Plan of Work - -Add `assets/skills/design-preflight/references/scenario-discrimination.md` as the single rule owner. Require one requirement-derived discriminator, a minimal contrast that exposes the nearest wrong meaning, fixed unrelated inputs when practical, and a terminal oracle. Split a Scenario Proof row when one contrast cannot prove every claimed outcome. - -Link Design Preflight, its card and challenger schema, the Adversarial Review packet, and reviewer lenses to the owner. Add the new fields to the existing Scenario Proof mapping. Do not copy the rule into routers or manuals. - -Add one integration test that protects unique ownership, routes, schema fields, and the rule guards. Update the README and operating manual with links only. Update the manifest after all distributed files are final. - -## Concrete Steps - -Work in `/home/mbeutler/Projects/codex-practical-kit`. - -Run: - - python3 /home/mbeutler/.codex/skills/.system/skill-creator/scripts/quick_validate.py assets/skills/design-preflight - python3 -m unittest tests.test_kit.IntegrationTests.test_scenario_proof_requires_a_discriminating_case - ./run-tests.sh - sh -n doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh - git diff --check - sha256sum --check MANIFEST.sha256 - -Record detailed results in `.agent/test-results/cpk-034-scenario-discrimination.md`. Never stage that file. - -## Validation and Acceptance - -The focused test must fail when the rule owner, a route, a discriminator field, a contrast field, or the split-row requirement is absent. The full suite must pass. - -Forward evidence must show that the general rule exposes all seven supplied shapes: cross-identity authorization, equal-baseline retained state, historical versus current value, staged rollover, zero versus absent, equal value under a new identity, and prior versus same-run state. - -One clean-context reviewer must inspect the staged candidate from base commit `e1d8ac887267590a763e733106121f79c927d121`. - -## Idempotence and Recovery - -The edits are static rules and tests. Validation commands are safe to repeat. If a command fails, stop and report the error. - -## Artifacts and Notes - -Preserve `.mcp.json`, `.repowise/`, and `.vscode/`. They are untracked environment state outside this task. - -## Interfaces and Dependencies - -The challenger scenario object gains `discriminator` and `contrast`. The Scenario Proof table gains matching columns. No runtime dependency or external service changes. - -Revision note: Created from the accepted CPK-034 plan and the supplied first-pass defect diagnostic. -Revision note: Recorded implementation and the corrected seven-shape forward test. -Revision note: Recorded final validation and documentation status before review. -Revision note: Recorded the clean staged-tree review and task closure. -Revision note: Recorded the authorized publication version and direct-integration path before delivery. -Revision note: Recorded the clean publication-candidate review before the version commit. diff --git a/docs/plans/cpk-035-adversarial-preflight-research.md b/docs/plans/cpk-035-adversarial-preflight-research.md deleted file mode 100644 index 1c77079..0000000 --- a/docs/plans/cpk-035-adversarial-preflight-research.md +++ /dev/null @@ -1,103 +0,0 @@ -# Make preflight adversarial and research-backed - -This ExecPlan is a living document until review closure. Maintain it according to `.agent/PLANS.md`. - -## Purpose / Big Picture - -After this change, Design Preflight first obtains an independent scenario derivation and then challenges the coordinator's actual decisions. Qualifying architecture, algorithm, protocol, and systems choices must use the pinned NeuroArxiv skill before an approach is selected. Read-only research and review can use available platform capacity, while only one write-capable implementation subagent can run at a time. - -## Progress - -- [x] (2026-08-19) Accepted the CPK-035 plan and created the isolated task branch. -- [x] (2026-08-19) Activated CPK-035 as the sole roadmap task. -- [x] (2026-08-19) Implemented the two-phase preflight challenge and concurrency correction. -- [x] (2026-08-19) Bundled pinned NeuroArxiv and made its qualifying research gate mandatory. -- [x] (2026-08-19) Updated tests and documentation, then forward-tested both workflows. -- [x] (2026-08-19) Passed final validation and a clean full review of staged tree `7d4caa6bfdabbca8f92818ffef1bdd5610a7c869`. - -## Surprises & Discoveries - -- Observation: The existing upstream staging and install loops are already data-driven. - Evidence: `kit.py` downloads every skill in `upstream.lock.json` and installs every name in `UPSTREAM_SKILLS`. -- Observation: NeuroArxiv borrows ADHD's isolated-reader pattern but has a narrower research purpose. - Evidence: The pinned upstream skill applies separate paper readers to arXiv research and does not provide general ideation guidance. -- Observation: The informed preflight phase rejected a plausible but unsupported operator-timing exclusion. - Evidence: The same challenger classified the post-cutoff save as an unsupported assumption, invalid exclusion, and unresolved contract gap after it received the incomplete coordinator card. -- Observation: The bundled workflow completed a real narrow systems search within platform capacity by running isolated readers in waves. - Evidence: Sequential arXiv API fetches returned four papers. The workflow selected a durable database state machine after four paper-specific abstract reads. - -## Decision Log - -- Decision: Use the same fresh challenger for an unanchored first pass and an informed adversarial second pass. - Rationale: The first pass preserves independent derivation. The second pass can test the coordinator's assumptions and exclusions instead of echoing them. - Date/Author: 2026-08-19 / user and Codex -- Decision: Bundle NeuroArxiv unchanged at commit `b5d20efa12dd1ba177ce890d56809d2e027f8055` and remove ADHD and NeuroArxiv from optional metadata. - Rationale: The existing pinned upstream mechanism supplies provenance and safe ownership without adding a dependency or copying upstream source into this repository. - Date/Author: 2026-08-19 / user and Codex -- Decision: Restrict one concurrent write-capable implementation subagent, not read-only agents. - Rationale: Parallel independent research and review are useful; concurrent writers create task-state and working-tree conflicts. - Date/Author: 2026-08-19 / user and Codex - -## Outcomes & Retrospective - -Implementation, forward testing, documentation, validation, and review are complete. The clean reviewer reported no findings. - -## Context and Orientation - -The task branch is `cpk-035-adversarial-preflight-research`. Its base branch is `main`, and its base commit is `038a3b8c6e9459d49845d1d42aa83be1f99b1cc7`. - -`assets/skills/design-preflight/SKILL.md` owns preflight procedure, and `assets/skills/design-preflight/references/preflight-review.md` owns challenger output. `assets/skills/research-first/SKILL.md` owns research selection. `assets/skills/delivery-lifecycle/references/coordination.md` owns agent roles. `kit.py` and `upstream.lock.json` own bundled-skill installation and provenance. `tests/test_kit.py` protects the installed interface. - -NeuroArxiv is an upstream skill that searches the arXiv API, assigns papers to isolated read-only agents, compares their evidence, and selects one path. A write-capable implementation subagent can edit files. A read-only agent can research or review but cannot edit files. - -## Product Boundary - -Apply [Scope boundaries](../../assets/skills/design-preflight/references/scope-boundaries.md). Toolkit rule files, routes, lock metadata, installer behavior, tests, and documentation are `composes`. Installed copies, user-managed ADHD, and tenant repository code are `opaque`. The toolkit must not adopt, overwrite, install, or remove user-managed ADHD. - -## Scenario Proof - -This task changes static policy and installation behavior, not product runtime behavior. The runtime Scenario Proof gate does not apply to the toolkit implementation itself. - -The preflight forward check must show that Phase 1 receives no coordinator card and that Phase 2 receives it and reports a seeded omission. The research forward check must show a qualifying open systems choice performs a real arXiv fetch through isolated readers, records citations and paper limitations, and selects one path. Structural tests must prove the research gate, fetch-failure stop, routine-work skip, concurrency boundary, exact upstream pin, conflict safety, and ADHD non-ownership. - -## Plan of Work - -Revise Design Preflight to run a two-phase challenge with one fresh read-only challenger. Extend the review interface with a `preflight-adversary` Phase 2 result and require dispositions for supported and rejected findings. - -Revise Research First to route qualifying open, costly architecture, algorithm, protocol, and systems choices through NeuroArxiv before selection. A failed required arXiv fetch stops selection. Retain official documentation and other primary sources for questions outside arXiv's scope. - -Add NeuroArxiv to `UPSTREAM_SKILLS` and to the lock at the accepted commit, blobs, and MIT license. Remove ADHD and NeuroArxiv from optional metadata. Do not add ADHD to obsolete or managed skills. Update routing and user documentation, then update the manifest. - -## Concrete Steps - -Work in `/home/mbeutler/Projects/codex-practical-kit`. - -Run the focused integration tests, all skill validators, `./run-tests.sh`, shell syntax checks, `git diff --check`, and `sha256sum --check MANIFEST.sha256`. Record detailed results in `.agent/test-results/cpk-035-adversarial-preflight-research.md` and never stage that file. - -## Validation and Acceptance - -Tests must fail if the exact NeuroArxiv pin, skill blob, license blob, install destination, required research trigger, fetch-failure stop, two-phase challenge packet, or one-writer boundary is removed. Installation tests must preserve an unrelated user-managed ADHD directory and reject an unowned NeuroArxiv destination. - -A fresh read-only forward test must apply the two challenge phases and find a seeded omission only after receiving the incomplete card. A separate clean-context forward test must apply the candidate research rule to a qualifying systems choice and return real arXiv citations, paper limitations, and one selected path. - -One clean-context reviewer must inspect the staged candidate from base commit `038a3b8c6e9459d49845d1d42aa83be1f99b1cc7`. - -## Idempotence and Recovery - -The edits and validation commands are safe to repeat. The installer uses its existing staged download and ownership checks. If a command fails, stop and report it unless an in-scope correction is clear. - -## Artifacts and Notes - -Preserve `.mcp.json`, `.repowise/`, and `.vscode/`. They are untracked environment state outside this task. - -The NeuroArxiv forward test cited arXiv `2608.03836`, `1911.11286`, `2302.04500`, and `2102.10185`. The readers used abstracts only. The selected test path was a durable database state machine with atomic claims and an idempotent effect ledger. This is validation evidence for the workflow, not an architecture decision for the toolkit. - -## Interfaces and Dependencies - -The bundled upstream skill is `neuroarxiv`, pinned at commit `b5d20efa12dd1ba177ce890d56809d2e027f8055`. Its `SKILL.md` Git blob is `cc47304c76f7cb53aa4e8a324702dc8e4f1d5639`; its `LICENSE` Git blob is `aaf95a45d3b11d68387ab0c3a0cee964a4ecd98c`; its license is MIT. No Node CLI or package dependency is bundled. - -The Phase 2 JSON result uses reviewer `preflight-adversary`. Each finding records its kind, source, coordinator claim, counterexample, wrong terminal result, required card change, and supported-model classification. Empty findings are valid. - -Revision note: Created from the accepted CPK-035 plan and verified upstream NeuroArxiv metadata. -Revision note: Recorded implementation and both clean-context forward tests. -Revision note: Recorded final validation, clean staged-tree review, and task closure. diff --git a/docs/plans/cpk-036-plan-history.md b/docs/plans/cpk-036-plan-history.md deleted file mode 100644 index 0a12469..0000000 --- a/docs/plans/cpk-036-plan-history.md +++ /dev/null @@ -1,137 +0,0 @@ -# Preserve Plan Mode decisions - -This ExecPlan is a living document until review closure. Maintain it according to `.agent/PLANS.md`. - -## Purpose / Big Picture - -After this change, a completed Plan Mode response remains available after context compaction, later planning, or task subdivision. The toolkit saves the exact response in an immutable Markdown record. Later planning agents must read and reconcile applicable records before they produce a new plan. - -## Progress - -- [x] (2026-08-19) Accepted the CPK-036 plan and completed the two-phase Design Preflight challenge. -- [x] (2026-08-19) Created the stacked `cpk-036-plan-history` task branch from reviewed CPK-035. -- [x] (2026-08-19) Activated CPK-036 as the sole roadmap task. -- [x] (2026-08-19) Implemented Plan history capture, retrieval rules, installation, and focused tests. -- [x] (2026-08-19) Updated user documentation and passed the clean-context forward test. -- [x] (2026-08-19) Passed the complete test suite, all skill validators, shell syntax checks, diff checks, and checksum validation. -- [x] (2026-08-19) Corrected two P2 findings, passed delta review, and passed final coherence review. - -## Surprises & Discoveries - -- Observation: Codex supplies `last_assistant_message` to normal Stop hooks, but the field is optional in the documented contract. - Evidence: The user accepted the native hook boundary. A missing value must produce a passive warning instead of unstable transcript parsing. -- Observation: RepoWise is a derived index and can omit a newly created record before its watcher updates. - Evidence: Direct file enumeration must remain the authority after RepoWise identifies the repository and related specifications. -- Observation: A successful Stop hook must return JSON, including a no-op result. - Evidence: The current OpenAI hook reference says that plain text is invalid. The hook now returns `{}` without continuation fields. -- Observation: A fresh planner recovered an ignored record that RepoWise did not index. - Evidence: The forward test cited the record and conflicting specification, emitted no plan, and requested the required supersession fields. -- Observation: Review found that a valid specification stem can contain glob syntax. - Evidence: Escaping the stem before discovery keeps identical retries idempotent for names such as `feature[1].md`. -- Observation: Same-event collision files can have different bytes. - Evidence: Deduplication must compare both the event key and content. Distinct collision evidence remains part of reconciliation. - -## Decision Log - -- Decision: Extend the existing managed hook script with passive Stop handling. - Rationale: The script already dispatches multiple hook events. This path needs no service, dependency, or second hook asset. - Date/Author: 2026-08-19 / user and Codex -- Decision: Store the complete final assistant message without byte normalization. - Rationale: The record must preserve the Plan Mode summary verbatim. - Date/Author: 2026-08-19 / user and Codex -- Decision: Use project files as authoritative storage and RepoWise only for discovery. - Rationale: File records survive index refreshes and can travel with the task. - Date/Author: 2026-08-19 / user and Codex -- Decision: Use the native Stop-hook contract and warn when the final message is absent. - Rationale: This matches observed Codex behavior without an App Server service or unstable transcript parser. - Date/Author: 2026-08-19 / user and Codex -- Decision: Return `{}` for every non-warning Stop result. - Rationale: Codex requires JSON from successful Stop hooks. An empty object does not continue or block the turn. - Date/Author: 2026-08-19 / Codex - -## Outcomes & Retrospective - -The toolkit now preserves exact completed Plan Mode responses and requires full-set reconciliation before later planning or resumed implementation. The first review found two idempotence and collision-evidence defects. Both corrections passed the complete test suite, a focused delta review, and final coherence review. - -## Context and Orientation - -The task branch is `cpk-036-plan-history`. Its direct base is reviewed CPK-035 commit `13a23b24cc7313c5fd652a1465a742287fb83c2a`. The isolation form is one local task branch. - -`assets/hooks/session_start.py` is the installed hook entry point. It handles Session Start and User Prompt Submit events. `kit.py` writes the managed hook entries in `config.toml`, installs custom skills, and checks installation state. `.agent/PLANS.md` owns ExecPlan behavior. `assets/AGENTS.block.md` routes tasks to installed skills. `tests/test_kit.py` owns installer and policy integration checks. - -A Plan history record is an immutable copy of one completed Plan Mode final response. It is evidence for later planning. It is not a second mutable implementation plan. - -## Product Boundary - -Apply [Scope boundaries](../../assets/skills/design-preflight/references/scope-boundaries.md). The hook, installer, Plan history skill, ExecPlan rules, routing, tests, and user documentation are `composes`. RepoWise indexes, user-owned hooks, project specifications, and installed records are `opaque`. An App Server client, transcript parser, database, daemon, mutable history index, review gate, and recovery of earlier lost plans are `deferred`. - -Normal use includes completed Plan Mode turns, zero or more related specification files, later Plan Mode turns, compaction, and normal hook retries. The supported model has one user, one Codex writer, a normal local filesystem, and Git. I/O faults, hostile markers, concurrent writers, symlinks, and interruption remain excluded under [Supported model](../../assets/skills/design-preflight/references/supported-model.md). - -## Scenario Proof - -Apply [Scenario discrimination](../../assets/skills/design-preflight/references/scenario-discrimination.md), [Owner composition](../../assets/skills/design-preflight/references/owner-composition.md), and [Full-set results](../../assets/skills/design-preflight/references/full-set-results.md). - -The input-domain checks must distinguish Plan Mode from other modes and one complete `` envelope from an incomplete response. The exact-byte case must contain Unicode and must contrast trailing-newline states. The terminal oracle is one record whose bytes equal `last_assistant_message`. - -The association checks must cover an explicit `none` marker, one valid specification, multiple valid specifications, invalid paths, missing files, path traversal, and a mixed valid-and-invalid set. Valid targets receive exact sibling copies. Any failed target also produces one unlinked copy and one passive warning. A missing marker is an association error, not an implicit no-spec declaration. - -The retained-state checks must cover an identical retry and a repeated event identity with different content. An identical retry creates no duplicate. Different content creates a collision record and preserves the first record. - -The collection checks must cover no history, one record, identical records from different turns, and duplicate-prefix records followed by a conflicting record. RepoWise can omit the final record in the check. Direct enumeration must still read every applicable record exactly once. - -The composed planning checks must cover a later Plan prompt, a compacted session, an unresolved specification conflict, and a recorded user supersession. An unresolved conflict produces no completed plan. A valid supersession cites the old record, gives the reason, and states the replacement decision. - -The installation checks must cover install, reinstall, doctor, uninstall, an obsolete managed Stop hook, and an unrelated user Stop hook. Installation leaves one current managed Stop entry. Uninstall preserves user hooks and all history records. - -## Plan of Work - -Add Plan history behavior to `assets/hooks/session_start.py`. Use only the Python standard library. Accept a completed plan only when the event is Plan Mode and the message contains one complete plan envelope. Parse exact `cpk-plan-spec` comments. Write valid associations beside each specification and write unlinked records under `.agent/plan-history/`. Use UTC capture time and a SHA-256 event key in each filename. - -Add one focused `plan-history` skill. It owns marker emission, complete file discovery, chronology, reconciliation, conflicts, and supersession records. Update `.agent/PLANS.md` with the narrow immutable-evidence exception and the implementation handoff rule. Route Plan Mode work to the skill from `assets/AGENTS.block.md` and the existing hook context. - -Add `Stop` to the managed hook events in `kit.py`. Keep the existing script command. Update exact ownership checks so upgrades remove obsolete toolkit Stop commands without removing unrelated hooks. Add `plan-history` to custom skill installation. - -Update current user documentation with the storage contract, warning boundary, and later-planning behavior. Update the checksum manifest after all distributed files are final. - -## Concrete Steps - -Work in `/home/mbeutler/Projects/codex-practical-kit`. - -Use focused unit and integration tests during implementation. Then run `./run-tests.sh`, skill validators, Python compilation, shell syntax checks, `git diff --check`, and `sha256sum --check MANIFEST.sha256`. Store detailed evidence in `.agent/test-results/cpk-036-plan-history.md`. Do not stage that file. - -Stage the complete candidate and make sure that no tracked change remains outside the index. Record the staged tree in the ignored result. Give one fresh read-only reviewer the accepted requirements, this Scenario Proof, the diff, the checks, and the supported-model boundary. - -## Validation and Acceptance - -An exact-byte hook test must fail before the implementation and pass afterward. It must compare the input and record as bytes. - -A clean-context forward test must start with an original plan and an intentionally stale RepoWise result. A later planner must find the omitted record through direct enumeration and reject an inverted subtask decision. - -Policy checks must reject an omitted Plan history route, missing marker contract, silent truncation, unrecorded supersession, or a second mutable plan owner. Installer checks must prove the current Stop entry and preserve unrelated hooks and records. - -## Idempotence and Recovery - -The implementation and validation commands are safe to repeat. Exact event retries are idempotent. A conflicting event never overwrites an earlier record. If a normal operation fails, stop and report the error. - -## Artifacts and Notes - -Preserve `.mcp.json`, `.repowise/`, and `.vscode/`. They are untracked environment state outside this task. - -The first Design Preflight pass independently selected passive file capture, full-set restoration, and immutable conflict evidence. The informed challenge added the missing-message contract gate, required association declarations, direct enumeration after RepoWise, mixed-target behavior, safe event keys, durable conflict resolution, visible warnings, and obsolete-hook upgrade coverage. - -## Interfaces and Dependencies - -A completed Plan Mode response contains one or more comments in this form: - - - -If no specification is known, the response contains this comment: - - - -For `docs/specification.md`, the hook writes `docs/specification.plan-summary...md`. Unlinked records use `.agent/plan-history/plan-summary...md`. The event key is the SHA-256 digest of `session_id`, a NUL byte, and `turn_id`. - -No new dependency or external service is permitted. - -Revision note: Created from the accepted Plan Mode design and both Design Preflight challenge phases. -Revision note: Recorded implementation, the current Stop output contract, and the clean-context forward test. diff --git a/docs/plans/cpk-037-stop-hook-context-limit.md b/docs/plans/cpk-037-stop-hook-context-limit.md deleted file mode 100644 index 3be4eea..0000000 --- a/docs/plans/cpk-037-stop-hook-context-limit.md +++ /dev/null @@ -1,51 +0,0 @@ -# Remove the invalid Stop context limit - -This ExecPlan is a living document until review closure. Maintain it according to `.agent/PLANS.md`. - -## Purpose - -Codex must load the managed Stop hook without a configuration warning. The installer must keep `additionalContextLimit` on context-producing hooks and omit it from Stop. - -## Progress - -- [x] (2026-08-19) Confirmed the warning in the installed configuration and the shared hook generator. -- [x] (2026-08-19) Confirmed the event restriction in the official OpenAI Hooks documentation. -- [x] (2026-08-19) Completed the small-change preflight and activated CPK-037. -- [x] (2026-08-19) Corrected generation and detection, and added the upgrade check. -- [x] (2026-08-19) Passed 51 tests, all skill validators, shell syntax checks, and diff checks. -- [x] (2026-08-19) Passed clean-context adversarial review and closed CPK-037. - -## Decision Log - -- Decision: Keep one managed hook generator and vary only the event-specific field. - Rationale: Stop cannot emit additional context. Session Start and User Prompt Submit still use the configured limit. - Date/Author: 2026-08-19 / Codex - -## Context - -The task branch is `cpk-037-stop-hook-context-limit`. Its base is `cpk-036-plan-history` commit `442c95f687c880bc07eb6434f7cc6cb01d5562ee`. The isolation form is one stacked local task branch. - -`kit.py` generates managed hook TOML and detects existing managed handlers. `tests/test_kit.py` verifies installation and upgrades. The official Hooks documentation states that Codex warns when `additionalContextLimit` appears on an event that cannot emit additional context. - -## Product Boundary - -The installer owns only its marked hook block. It must preserve unrelated handlers and configuration. This correction does not change Stop execution or Plan history storage. - -## Scenario Proof - -| Scenario | Discriminator | Contrast | Production path | Required oracle | Runnable test or command | Result | -| --- | --- | --- | --- | --- | --- | --- | -| Generate current hooks | Hook event | Stop versus Session Start and User Prompt Submit | `hooks_config_block` to TOML parser | Stop has no limit; the other managed hooks have `1200` | `test_reinstall_accepts_existing_config_toml_hook` | Passed | -| Upgrade the faulty block | Existing Stop field | Legacy managed block versus corrected block | `install_hooks` removes and regenerates the marked block | Reinstalled Stop has no limit and no duplicate handler | `test_reinstall_removes_stop_context_limit` | Passed | - -## Scope Ceiling - -Do not add a new hook format, parser, service, dependency, or event registry. Do not change unrelated user configuration. - -## Validation - -Run the focused installer tests, `./run-tests.sh`, `git diff --check`, and `sha256sum --check MANIFEST.sha256`. Store detailed results in `.agent/test-results/cpk-037-stop-hook-context-limit.md`. - -## Outcomes - -The installer now omits `additionalContextLimit` from Stop. It retains the limit on Session Start and User Prompt Submit. Reinstallation also removes the invalid field from the prior managed block. diff --git a/docs/plans/cpk-038-shared-roadmap-view.md b/docs/plans/cpk-038-shared-roadmap-view.md deleted file mode 100644 index bdc31ef..0000000 --- a/docs/plans/cpk-038-shared-roadmap-view.md +++ /dev/null @@ -1,88 +0,0 @@ -# Keep one live roadmap view across worktrees - -This ExecPlan is a living document until review closure. Maintain it according to `.agent/PLANS.md`. - -## Purpose - -Users must be able to keep one roadmap file open while Codex works in linked Git worktrees. `docs/roadmap.md` remains the only roadmap authority. The toolkit generates a stable, read-only projection in the primary checkout after an actual roadmap edit. - -## Progress - -- [x] (2026-08-19) Recovered the accepted Plan Mode response and stored it beside this ExecPlan. -- [x] (2026-08-19) Completed adversarial design preflight and official Codex hook research. -- [x] (2026-08-19) Created the isolated `cpk-038-shared-roadmap-view` worktree from CPK-037. -- [x] (2026-08-19) Implemented the managed edit hooks and generated view lifecycle. -- [x] (2026-08-19) Updated the roadmap authority and user documentation. -- [x] (2026-08-19) Passed 57 tests, Python compilation, shell syntax, skill validation, diff checks, and manifest checksums. -- [x] (2026-08-19) Corrected the parent-path collision from full review pass 1. -- [x] (2026-08-19) Completed delta and coherence review, then closed the task. - -## Prior Plan Reconciliation - -- `.agent/plan-history/plan-summary.20260819T195712262086Z.manual-recovery.md`: carried. The Plan history hook did not create its normal record, so the exact completed response was recovered from the thread before implementation. - -## Plan Deviations - -No accepted decision has changed. - -## Surprises and Discoveries - -- Observation: The patch path can identify a linked worktree even when hook `cwd` identifies the original checkout. - Evidence: The first focused implementation test used the linked worktree as `cwd`. Self-review reproduced the real `../linked/docs/roadmap.md` form and required target-owned root discovery. -- Observation: A user-owned `.codex` file is a collision before `.codex/roadmap-view.md` exists. - Evidence: Full review pass 1 showed that directory creation failed only after the exclusion changed. The collision guard now checks the parent path first. - -## Decision Log - -- Decision: Generate `.codex/roadmap-view.md` only after an exact roadmap edit changes the source bytes. - Rationale: Session startup does not prove which worktree is authoritative. - Date/Author: 2026-08-19 / Codex -- Decision: Pair `PreToolUse` and `PostToolUse` fingerprints instead of interpreting tool output. - Rationale: The official hook contract defines the tool input but does not define one stable success shape for `tool_response`. - Date/Author: 2026-08-19 / Codex -- Decision: Keep global uninstall repository-agnostic, but let `remove-repo` delete owned projection state. - Rationale: Global installation has no safe list of every repository touched by runtime hooks. - Date/Author: 2026-08-19 / Codex - -## Context - -The task worktree is `/home/mbeutler/Projects/codex-practical-kit-cpk-038` on branch `cpk-038-shared-roadmap-view`. It is stacked on CPK-037 commit `4ae47a1c5dffc2cc6e8d2a690f8041e4b54b2d82`, which already restricts `additionalContextLimit` to context-producing hooks. - -`assets/hooks/session_start.py` dispatches all current managed hook events. `kit.py` installs and detects the marked `config.toml` hook block. `tests/test_kit.py` exercises installation and hook payloads. The official Codex Hooks documentation defines `PreToolUse` and `PostToolUse` support for `apply_patch`, including `cwd`, `tool_use_id`, and `tool_input.command`. - -## Product Boundary - -`docs/roadmap.md` remains the only roadmap authority and the only agent write target. `.codex/roadmap-view.md` is a generated human projection. The supported model is one active roadmap writer in a normal non-bare Git repository. Manual edits, concurrent writers, deletion or rename synchronization, symlinked layouts, submodules, retries, and recovery are excluded. - -## Scenario Proof - -| Scenario | Discriminator | Production path | Required oracle | Runnable check | Result | -| --- | --- | --- | --- | --- | --- | -| First roadmap creation | Absent file becomes present | Pre-hook fingerprint to post-hook projection | Owned view and exclusion appear with unchanged source bytes | focused hook test | Passed | -| Linked-worktree update | Source checkout differs from primary checkout | Exact patch path to shared Git directory | Primary view contains linked-worktree roadmap, not primary source | focused hook test | Passed | -| Failed or no-op patch | Source fingerprint does not change | Paired hook state | Existing view and exclusion remain byte-identical | focused hook test | Passed | -| Complete patch scan | Lookalike precedes exact operation | Full operation parser | Later exact roadmap operation refreshes the view | focused hook test | Passed | -| Unrelated or lookalike edit | Resolved target differs | Exact normalized path guard | No projection state changes | focused hook test | Passed | -| User-owned collision | Destination or parent path is user-owned | Collision check before exclusion | File, exclusion, and Git visibility stay unchanged; one warning appears | focused hook tests | Passed | -| Hook lifecycle | Managed versus unrelated handlers | Install, reinstall, uninstall | Exact managed matchers are present once; unrelated hooks remain | installer tests | Passed | -| Repository removal | Owned versus user-owned projection | `remove-repo` cleanup | Only owned view and exclusion block are removed | integration test | Passed | - -## Implementation - -Reuse the existing hook script and Python standard library. Parse all `*** Add File:` and `*** Update File:` headers from `tool_input.command`. Resolve them against `cwd`, and retain only the exact roadmap under that worktree root. - -On `PreToolUse`, store the source fingerprint in temporary state keyed by the session and tool-use identifiers. On `PostToolUse`, remove that state, compare the live source, and continue only when the bytes changed. Resolve the primary checkout from the absolute shared Git directory. Check destination ownership before adding a marked block to the common `info/exclude`. Replace the owned view with a generated banner plus source content. Emit no output on success and one `systemMessage` on an applicable failure. - -Add managed `PreToolUse` and `PostToolUse` groups with matcher `^apply_patch$`. Preserve unrelated hooks. Keep `additionalContextLimit` only on Session Start and User Prompt Submit. - -Teach `remove-repo` to remove the owned view and marked exclusion block. Do not enumerate repositories during global uninstall. - -Update Roadmap Maintainer as the sole rule owner. Add a short user procedure that tells users to open the generated view and edit only the tracked roadmap. - -## Validation - -Run focused installer and hook tests, `./run-tests.sh`, Python compilation, shell syntax checks, `git diff --check`, and `sha256sum --check MANIFEST.sha256`. Store detailed results in `.agent/test-results/cpk-038-shared-roadmap-view.md`. - -## Outcomes - -The implementation is complete and validated. Full review pass 1 found one P2 collision defect. The correction passed delta review, and the complete task passed final coherence review. diff --git a/docs/plans/cpk-039-native-windows.md b/docs/plans/cpk-039-native-windows.md deleted file mode 100644 index a95117b..0000000 --- a/docs/plans/cpk-039-native-windows.md +++ /dev/null @@ -1,191 +0,0 @@ -# Add native Windows compatibility - -This ExecPlan is a living document until review closure. Maintain it according to `.agent/PLANS.md`. - -## Purpose - -Windows users must be able to operate every root toolkit entry point with PowerShell 7. The required RepoWise MCP server must start without a POSIX shell. Existing macOS and Linux commands must continue to work. - -## Progress - -- [x] (2026-08-19) Recovered the accepted Plan Mode response and stored it beside this ExecPlan. -- [x] (2026-08-19) Completed official platform research and two-phase adversarial design preflight. -- [x] (2026-08-19) Created `cpk-039-native-windows` from CPK-038 commit `66a8db7fb4627a4a281d21a0a7965a40f85f5ca3` in a linked worktree. -- [x] (2026-08-19) Implemented PowerShell entry points and platform-aware tool installation. -- [x] (2026-08-19) Replaced the shell-only RepoWise bootstrap with one cross-platform Python runtime. -- [x] (2026-08-19) Updated user instructions, the release manifest, the lock, and version surfaces. -- [x] (2026-08-21) Recorded the failed native Windows test checkpoint and completed a two-phase correction preflight. -- [x] (2026-08-21) Reproduced the uv installer failure and isolated PowerShell statement-at-a-time parsing as its cause. -- [x] (2026-08-21) Passed 67 tests through both local launchers after the uv invocation correction. -- [x] (2026-08-21) Removed ambient Windows `python` resolution from the PowerShell launcher tests and bounded their subprocess runtime. -- [x] (2026-08-21) Defined an ownership-safe Windows recovery path for a RepoWise launcher broken by Python replacement. -- [x] (2026-08-21) Completed clean correctness review of the RepoWise recovery candidate. -- [x] (2026-08-21) Validated two Windows review findings and completed a two-phase correction preflight. -- [x] (2026-08-21) Stopped the complete Windows watcher tree and passed 73 tests through `run-tests.ps1` with ambient RepoWise on `PATH`. -- [x] (2026-08-21) Corrected the Windows repository-cleanup command found by the final coherence review. -- [x] (2026-08-21) Bound subprocess text decoding to UTF-8 after exact-commit validation exposed a cp1252 reader error. -- [x] (2026-08-21) Passed local validation and exact-commit native Windows validation at `d5957f81b61893934a046446d8fdf0f8cf62c7c8`. -- [x] (2026-08-21) Completed adversarial review and review closure after six passes, including the validation correction. - -## Prior Plan Reconciliation - -- `.agent/plan-history/plan-summary.20260819T211423672232Z.manual-recovery.md`: carried. The Plan history hook could not link the completed response before this ExecPlan existed. This immutable copy preserves the exact response from the thread. - -No earlier Plan history record applies to CPK-039. - -## Plan Deviations - -- Native checkpoint `a80ca4f446e9c1d73e20b1b18d33d716072ddd4c` is superseded only as validation evidence. -- The accepted scope is unchanged. The correction changes the Windows test environment, host-specific test contracts, and checkout bytes. -- The first correction did not rewrite `kit.py` or the RepoWise bootstrap. The uv correction changes one `ensure_uv` command argument. -- Native installation at `9850d63` proved that `pwsh -Command -` did not execute the verified multi-line uv installer as one script. The next correction changes only the `ensure_uv` PowerShell invocation and its direct test. -- The reported Python replacement adds one Windows-only recovery case. A failed RepoWise launcher is repairable only when the previous manifest records the selected fixed user-bin path. -- The correction stops the complete Windows watcher process tree and isolates the recovery fixture from ambient executable discovery. It does not change POSIX shutdown. -- The coherence correction splits the repository-cleanup command by platform. Windows uses `python`; macOS and Linux retain `python3`. -- Exact-commit validation reopened the candidate after RepoWise output caused a cp1252 decoder error. The shared subprocess owner now decodes UTF-8 and replaces malformed bytes. - -## Surprises and Discoveries - -- Observation: The Plan history hook requires the marked specification file to exist before it can store a linked record. - Evidence: No CPK-039 record existed in `.agent/plan-history/` or beside the future specification after Plan Mode ended. -- Observation: PowerShell can leave `$LASTEXITCODE` unset after command resolution fails. - Evidence: The first local `doctor.ps1` check reported a missing `python` command but returned status 0. Each launcher now catches this error and returns status 1. -- Observation: Native Windows validation found 11 errors and 9 failures in the test checkpoint. - Evidence: Python used cp1252 for repository text. Some tests selected the wrong host command or platform branch. - Evidence: One excluded migration fixture required link privilege. Windows paths and Git checkout conversion changed test results. -- Observation: PowerShell returned zero after it skipped the body of a multi-line installer received through `-Command -`. - Evidence: A local executable check reproduced a missing marker with status zero. Evaluating the complete input as one script block created the marker. -- Observation: The launcher-forwarding test could wait indefinitely on the host's ambient Windows `python` command. - Evidence: The test did not bind the temporary launcher to the interpreter that started the suite and had no subprocess timeout. -- Observation: A retained `repowise.exe` can become non-executable after its Python installation is replaced. - Evidence: Native reinstall reported the removed Python 3.14 path, but classified the manifest-recorded launcher as a different RepoWise version. -- Observation: `Popen.terminate()` stops only the uv console launcher on Windows. - Evidence: A native smoke check left the Python watcher alive and immediate repository cleanup failed with `WinError 32`. -- Observation: The Windows recovery fixture selected the user's installed RepoWise before its temporary launcher. - Evidence: `run-tests.ps1` failed with the ambient `C:\Users\mikeb\.local\bin\repowise.exe` and passed when that path was absent. -- Observation: The shared uninstall text used the POSIX-only `python3` command for Windows users. - Evidence: The supported native Windows installation exposes `python.exe` and does not require a `python3` alias. -- Observation: `setup-repo.ps1` completed while a subprocess reader thread failed to decode RepoWise UTF-8 output as cp1252. - Evidence: Exact-commit clone `1f0a784d61653c75dd5b0e9dec4769e32834da2b` emitted `UnicodeDecodeError` from `subprocess.py` before Doctor reported ready. - -## Decision Log - -- Decision: Support PowerShell 7 with `.ps1` entry points only. - Rationale: The user does not require Windows PowerShell 5.1 or batch launchers. - Date/Author: 2026-08-19 / User and Codex -- Decision: Install one Python RepoWise bootstrap instead of a second PowerShell implementation. - Rationale: One standard-library runtime keeps lifecycle behavior identical across platforms. - Date/Author: 2026-08-19 / Codex -- Decision: Require native VM evidence for the exact pushed checkpoint before correctness review. - Rationale: Local PowerShell on Linux cannot prove Windows process and path behavior. - Date/Author: 2026-08-19 / User and Codex -- Decision: Stop a live Windows watcher with one `taskkill /T /F` operation, discard its output, and then wait for the launcher. - Rationale: Windows `taskkill /T` ends the selected process and its children. Job Objects require custom Win32 lifecycle code, and console signals require console attachment. - Sources: https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/taskkill and https://docs.python.org/3/library/subprocess.html#subprocess.Popen.terminate - Date/Author: 2026-08-21 / Codex - -## Outcomes and Retrospective - -The five PowerShell entry points and the cross-platform RepoWise bootstrap are implemented. Exact-commit native Windows validation passes. Adversarial review is clean after the watcher, fixture-isolation, cleanup-command, and UTF-8 corrections. - -## Context and Orientation - -The task worktree is `/home/mbeutler/Projects/codex-practical-kit-cpk-039`. The branch is `cpk-039-native-windows`, based on completed CPK-038 commit `66a8db7fb4627a4a281d21a0a7965a40f85f5ca3`. - -The root launchers are thin entry points for `kit.py`. This module owns installation, configuration, RepoWise setup, Doctor, and uninstall behavior. - -The installed Python bootstrap prepares RepoWise before it starts the MCP server. Its source is `assets/runtime/repowise_bootstrap.py`. - -`tests/test_kit.py` owns the executable contract checks. `README.md`, `CODEX-INSTALL-PROMPT.md`, and `docs/REPOWISE.md` own user instructions. - -## Product Boundary - -Apply [Scope boundaries](../../assets/skills/design-preflight/references/scope-boundaries.md). The current production use cases are installation, testing, eager repository setup, Doctor, uninstall, and automatic RepoWise MCP startup. - -The task composes the five Windows entry points, platform tool selection, bootstrap installation, MCP configuration, user instructions, manifest, lock, version, and tests. Existing POSIX outcomes and managed hook `commandWindows` behavior are opaque and must remain unchanged. There is no deferred owner. - -The supported model is one user on native Windows 10 or 11 with PowerShell 7, Python 3.11 or later, Git, and Codex. macOS and Linux remain supported. A Windows reinstall repairs a failed RepoWise launcher only when the previous manifest records the selected fixed user-bin path. The task excludes PowerShell 5.1, batch files, Windows CI, WSL-only support, dependency installation for Python or Git, other recovery, retries, concurrency, and changes to managed install locations. - -## Scenario Proof - -Apply [Scenario discrimination](../../assets/skills/design-preflight/references/scenario-discrimination.md) and [Owner composition](../../assets/skills/design-preflight/references/owner-composition.md). - -| Scenario | Discriminator and contrast | Production path | Required oracle | Runnable check | Result | -| --- | --- | --- | --- | --- | --- | -| Distributed artifact set | Each current `.sh` entry point versus its peer; LF versus converted checkout bytes | Git attributes and source inventory to manifest | Exactly five `.ps1` peers and one bootstrap source occur once with valid hashes after a checkout with `core.autocrlf=true` | `test_windows_launchers_and_runtime_are_complete_distribution_artifacts`; fresh clone with `core.autocrlf=true` | Passed exact-commit native clone | -| Action launcher | Simple argument versus path with spaces; success versus error | `.ps1` to Python subcommand | Arguments and exit status remain unchanged | `test_action_launchers_forward_arguments_and_exit_status`; `test_action_launcher_reports_missing_python` | Passed locally | -| Test launcher | Passing unit phase versus failing unit phase; cp1252 default versus inherited UTF-8 mode | unit discovery and child hooks to Python compilation | Success reads UTF-8 and compiles every source; failure does not compile | `test_test_launcher_compiles_kit_and_every_hook`; `test_test_launcher_stops_after_failed_unit_phase`; native `run-tests.ps1` | Passed exact-commit native clone | -| Hook command syntax | POSIX `command` versus `commandWindows` | generated TOML to hook subprocess | The host-specific command starts the hook and preserves exact output | `test_plan_mode_prompt_selects_normal_mode` | Passed exact-commit native clone | -| Hook interpreter | `python3` alias versus the current interpreter | test subprocess to Session Start JSON | The router test uses the interpreter running the suite | `test_session_start_still_announces_router` | Passed exact-commit native clone | -| Platform-specific unit contracts | Unmocked host versus explicit POSIX and Windows predicates | test fixture to uv and RepoWise selectors | Each test proves its named platform branch on either host | missing-uv and missing-RepoWise POSIX and Windows tests | Passed exact-commit native clone | -| Existing Windows executables | Present `uv.exe` and `repowise.exe` versus absent names | platform discovery to runtime result | Existing commands are reused without installation | `test_windows_runtime_discovery_uses_executable_suffix` | Passed locally | -| Missing Windows uv | Missing `uv.exe` versus the POSIX missing path; statement stream versus one script block | download, hash, and `pwsh` stdin | The exact verified installer executes as one script and creates `uv.exe` in `UV_INSTALL_DIR` | `test_missing_windows_uv_runs_verified_powershell_installer_once`; executable multi-line installer check | Passed exact-commit native clone | -| Missing Windows RepoWise | Missing `repowise.exe` after uv is ready | uv tool installation to discovery | One pinned persistent tool install returns `repowise.exe` | `test_missing_windows_repowise_uses_executable_result` | Passed locally | -| Broken recorded Windows RepoWise | Nonzero version result with both manifest and fixed-target ownership versus either predicate absent; ambient RepoWise present versus absent | fixture-scoped discovery, reinstall through runtime selection, forced uv replacement, and manifest writer | The temporary launcher is probed, one forced pinned install replaces its stale bytes, and the completed manifest records `repowise.exe` | `test_install_repairs_manifest_owned_broken_windows_repowise`; full `run-tests.ps1` with ambient RepoWise | Passed native Windows | -| Unowned, wrong-version, and POSIX commands | Broken unowned path versus broken owned Windows path; successful 0.40.0 versus failed process; Windows versus POSIX | selection and validation gate | Unowned, successful wrong-version, and POSIX commands stop without mutation | ownership, version, reuse, and POSIX runtime tests | Passed locally | -| Watcher platform | Valid POSIX shebang versus Windows executable | bootstrap watcher selector | POSIX uses patched Python; Windows uses `repowise.exe watch` | `test_watch_command_is_platform_specific` | Passed exact-commit native clone | -| Watcher cleanup | Windows launcher plus child versus launcher-only termination; cleanup output versus MCP stdout | bootstrap cleanup after normal MCP completion | Both watcher processes exit before return, the repository is immediately removable, and cleanup emits no MCP stdout | `test_windows_bootstrap_stops_complete_watcher_tree`; `test_stop_watcher_is_platform_specific`; stream-ownership test | Passed native Windows | -| Watcher readiness | Watcher stays alive versus exits during the gate | watcher to MCP terminal owner | Early exit returns nonzero and MCP never starts | `test_bootstrap_stops_when_watcher_fails_to_start` | Passed locally | -| Existing Git lifecycle | Missing index versus existing index; no `HEAD` versus `HEAD` | bootstrap through watcher, MCP, and cleanup | Init occurs once, hook occurs always, update needs `HEAD`, and cleanup occurs | `test_bootstrap_initializes_once_and_always_installs_hook` | Passed locally | -| Empty and non-empty non-Git folders | Empty directory versus one existing file | bootstrap through terminal owner | Empty path gets the full no-update lifecycle; non-empty path remains unchanged and starts only MCP | `test_bootstrap_initializes_only_empty_non_git_directory` | Passed locally | -| MCP stream ownership | Bootstrap diagnostics versus MCP bytes | subprocess streams | Diagnostics use stderr; stdout contains only foreground MCP bytes | `test_bootstrap_keeps_setup_diagnostics_off_mcp_stdout` | Passed locally | -| Install and Doctor | Managed block versus unrelated TOML | install to Doctor | Python bootstrap command is valid; hooks and unrelated TOML remain | installer tests and isolated `kit.py doctor` | Passed exact-commit native clone | -| Eager setup | Repository without `HEAD` versus with `HEAD` | setup entry point to RepoWise | Both initialize and install the hook; only the latter updates | `test_setup_skips_catch_up_before_first_commit`; `test_setup_preserves_roadmap_and_unrelated_blocks` | Passed locally | -| Uninstall ownership | Normal uninstall versus `--purge` | ownership manifest to filesystem | Normal mode retains the runtime root; purge removes it | `test_install_preserves_global_config_and_uninstall_removes_owned_block` | Passed locally | -| Repository cleanup command | Windows `python` versus POSIX `python3` | README uninstall instructions to `kit.py remove-repo` | Each supported platform receives a command that resolves its required interpreter | `test_windows_launchers_and_runtime_are_complete_distribution_artifacts` | Passed locally | -| Subprocess text encoding | UTF-8 output under a cp1252 Windows locale versus ASCII output | `kit.run` pipe reader to command result | UTF-8 output decodes without a reader-thread error; malformed bytes cannot crash the reader | `test_run_decodes_utf8_subprocess_output`; native `setup-repo.ps1` | Passed exact-commit native clone | -| Native release gate | Local proof versus exact pushed Windows commit | checkpoint to Codex MCP use | Windows tests pass and a fresh Codex session can use RepoWise | user VM record bound to commit | Passed at `d5957f81b61893934a046446d8fdf0f8cf62c7c8` | - -## Plan of Work - -First add the five thin PowerShell files and tests for argument, exit, and test-phase behavior. Use `python`, `$PSScriptRoot`, `@args`, and `$LASTEXITCODE`. Do not add a shared PowerShell helper. - -Then add small platform helpers in `kit.py`. Select executable suffixes and the pinned uv installer by the running platform. Keep the current POSIX path unchanged. Add the Windows installer URL and SHA-256 to `upstream.lock.json`. - -For retained runtime recovery, keep `ensure_repowise` as the only owner. Probe process status and output. Force the existing pinned uv install only after a nonzero Windows result when the manifest path, selected path, and fixed user-bin path are equal after platform normalization. Do not delete a launcher. Keep command-start errors, POSIX failures, unowned failures, and successful wrong versions as hard stops. - -Move bootstrap behavior into `assets/runtime/repowise_bootstrap.py`. Use only Python standard-library process and path functions. Copy this file into the managed runtime during installation. Generate the RepoWise MCP table with `sys.executable` and an argument array that names the installed bootstrap and RepoWise executable. - -Update Doctor and eager setup to use the same selected executables. Preserve normal uninstall ownership and remove the runtime root only during purge. - -Update the authoritative user instructions and the publication procedure. Set the feature version to `0.19.0`. Regenerate `MANIFEST.sha256` after all tracked content is final. - -## Concrete Steps - -Work in `/home/mbeutler/Projects/codex-practical-kit-cpk-039`. - -Run local validation with: - - ./run-tests.sh - pwsh -File ./run-tests.ps1 - sh -n doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh - git diff --check - sha256sum --check MANIFEST.sha256 - -After local validation, make and push one checkpoint. Force the reported normal Windows conversion setting during a fresh clone: - - git -c core.autocrlf=true clone --branch cpk-039-native-windows --single-branch https://github.com/calculatetech/codex-practical-kit.git codex-practical-kit-cpk-039 - -In the VM, run `run-tests.ps1`, install, `setup-repo.ps1 .`, and Doctor. Start a fresh Codex session in the clone. Make sure that RepoWise initializes and answers one codebase query. Save `.repowise/.update.log` evidence. Test normal uninstall, reinstall, and purge. - -Record the exact commit and results in `.agent/test-results/cpk-039-native-windows.md`. If later work changes a Windows command, installed artifact, checksum, configuration, or validation step, push a new checkpoint and repeat the affected native checks. - -## Validation and Acceptance - -All existing POSIX tests must pass. Every Scenario Proof row must name its actual test and result before review. Native acceptance requires a successful RepoWise MCP start and tool call from the exact pushed commit. - -Finalize substantive documentation before the checkpoint. Start adversarial review only after the native result passes. - -## Idempotence and Recovery - -Installation and repository setup are repeatable. Each external operation gets one attempt. If an operation fails, stop and report the error. Do not add retry or recovery behavior. - -## Artifacts and Notes - -The Windows uv installer is `https://astral.sh/uv/0.12.4/install.ps1`. Its accepted SHA-256 is `76a0c027f3d47a7ced56f9e63e67a21cb1bcbf525c8ba9ef7ec0d633cc8f89e4`. - -The preflight adversary required independent proof for executable discovery, uv installation, RepoWise installation, watcher selection, watcher failure, stream ownership, artifact completeness, uninstall ownership, and exact-commit VM validation. These cases are present in the Scenario Proof. - -## Interfaces and Dependencies - -The public interface adds five PowerShell 7 commands beside the existing shell commands. The managed RepoWise MCP command changes from `/bin/sh -c ` to ` `. No new dependency or public configuration key is added. diff --git a/docs/plans/cpk-040-plan-history-capture.md b/docs/plans/cpk-040-plan-history-capture.md deleted file mode 100644 index 78dfbda..0000000 --- a/docs/plans/cpk-040-plan-history-capture.md +++ /dev/null @@ -1,96 +0,0 @@ -# Save Plans at acceptance - -This ExecPlan is a living document until review closure. Maintain it according to `.agent/PLANS.md`. - -## Purpose - -An implementation acceptance prompt must save the preceding completed Plan before implementation work starts. Later agents must find every saved repository Plan in `.agent/plan-history/` without knowing its specification path. - -## Progress - -- [x] (2026-08-22) Inspected this chat rollout before fetching, branching, editing, installing, or creating task files. -- [x] (2026-08-22) Confirmed the accepted Plan, null `last_agent_message`, following acceptance turn, missing history record, and missing managed `SessionEnd` hook. -- [x] (2026-08-22) Created branch `cpk-040-plan-history-capture` from `ec07371a49480b10c5f5e6625624fcf329e3fd4a`. -- [x] (2026-08-22) Preserved the accepted Plan in repository and sibling history with byte-for-byte comparison to the rollout. -- [x] (2026-08-22) Implemented transcript capture, central discovery storage, lifecycle hooks, and the `0.19.1` version. -- [x] (2026-08-22) Passed the focused checks and all 79 default Python checks. -- [x] (2026-08-22) Updated the canonical Plan history rules and affected user documentation. -- [x] (2026-08-22) Completed clean full and test-delta reviews. -- [x] (2026-08-22) Installed version `0.19.1`, passed Doctor, and passed the live Codex acceptance check. -- [x] (2026-08-22) Corrected and reviewed the managed `SessionEnd` timeout after Codex reported its 3-second maximum. - -## Prior Plan Reconciliation - -Record: `docs/plans/cpk-036-plan-history.md` - -Status: superseded - -Reason: Codex 0.149 completes Plan turns without the expected `Stop` hook. Specification-only records are also not globally discoverable. - -Replacement: Save the newest completed Plan during the next `UserPromptSubmit`, including an implementation acceptance prompt. Also capture during supported session lifecycle events and retain `Stop` compatibility. - -The accepted CPK-040 response is recovered from this chat rollout and linked beside this ExecPlan. - -## Plan Deviations - -- The accepted Plan contains the literal opening envelope tag in its diagnostic text. The existing count-based validator rejects that normal Plan. The shared validator must recognize the outer boundary without rejecting tag text inside the Plan. -- The current hook cannot perform the required manual recovery until that shared validator is corrected. Run recovery immediately after the correction and before unrelated runtime work. -- The live client must declare the Codex `experimentalApi` capability. It waits for the managed `hook/completed` event because `turn/started` occurs before prompt hooks. -- Official Codex documentation caps `SessionEnd` at 3 seconds. The first candidate incorrectly reused the 10-second timeout from other hooks. - -## Production Evidence - -The source rollout is `/home/mbeutler/.codex/sessions/2026/08/13/rollout-2026-08-13T20-56-24-019ffdc5-27d6-7583-9a3b-7499d22ed915.jsonl`. - -Thread `019ffdc5-27d6-7583-9a3b-7499d22ed915` contains completed Plan turn `01a027d1-1ffc-7463-8292-00d9b3ffde26`. The turn has a completed `Plan` item, an assistant `final_answer`, and `task_complete` with `last_agent_message: null`. Turn `01a027d4-0287-7322-9b03-d2e78bc26d8f` then starts with `Implement the plan.`. The installed hook did not create a repository or sibling record. - -The assistant turn also contains commentary messages. Therefore, transcript selection must require the final-answer envelope. Turn identity alone is not sufficient. - -## Product Boundary - -Apply [Scope boundaries](../../assets/skills/design-preflight/references/scope-boundaries.md). The task composes the managed hook, hook installer, immutable record writer, and canonical Plan history skill. Codex rollout and hook schemas are opaque platform owners. Repository history and valid specification siblings are terminal file owners. - -The supported model is one current Codex session in a Git repository. The next prompt, session start, or clean session end supplies the current transcript. Historical all-session recovery, crashes that bypass every lifecycle event, daemons, databases, mutable cursors, dependencies, and automatic mode switching are excluded. - -## Scenario Proof - -| Scenario | Discriminator and contrast | Production path | Required oracle | Runnable check | Result | -| --- | --- | --- | --- | --- | --- | -| Acceptance capture | Completed Plan followed by `Implement the plan.` versus no completed Plan | `UserPromptSubmit` to transcript reader to record writer | Exact Plan exists before hook return | Real-rollout fixture acceptance test | Passed | -| Structural envelope | Outer envelope with an inline opening-tag mention versus incomplete outer envelope | shared Plan validator | Valid outer envelope passes; incomplete response fails | focused validator test | Passed | -| Lifecycle capture | default prompt, resume, compact, clear, and session end | managed hook event to transcript reader | Latest completed Plan is saved without changing hook output shape | hook subprocess tests | Passed | -| Turn selection | Final Plan response versus commentary and newer non-Plan turn | reverse rollout reader | Only the newest completed turn can produce a record | observed-shape selection tests | Passed | -| Event identity | Stop replay versus transcript replay; equal text from distinct turns | shared session and turn identity to immutable writer | Same turn is idempotent; distinct turns remain distinct | identity and collision tests | Passed | -| Discovery and association | linked, none, invalid, and mixed markers | central history plus sibling writers | Every repository Plan has a central record and every valid sibling | association tests | Passed | -| Bounded read | large prefix, non-Plan suffix, and no-Plan transcript | reverse reader to newest completed turn | Old transcript content is not repeatedly scanned | large-prefix and newest-non-Plan checks | Passed | -| Live acceptance | app-server Plan turn followed by acceptance | real Codex to installed hook | Raw final response is saved when the synchronous prompt hook completes | opt-in live test | Passed | - -## Plan of Work - -Correct the shared envelope validator first. Recover the accepted Plan through that owner. Then add one standard-library reverse transcript reader and call it from `UserPromptSubmit`, `SessionStart`, and `SessionEnd`. Keep direct `Stop` capture. - -Always write repository Plans to `.agent/plan-history/`. Also write each valid specification sibling. Preserve the existing global fallback for non-Git paths and every hook output contract. - -Update the installer, Doctor, canonical Plan history instructions, user documentation, and committed version. Add no dependency or background process. - -## Validation and Acceptance - -Run focused hook and installer checks, the full suite, shell checks, rule-owner checks, and `git diff --check`. Finalize documentation before adversarial review. - -After clean review, install the candidate with `python3 kit.py install --repo .` and run `python3 kit.py doctor --repo .`. Run the opt-in app-server acceptance check against the installed toolkit. - -## Idempotence and Recovery - -The session and original turn form the immutable event identity. An exact retry writes nothing. Different content for one identity creates a collision record. The reader inspects only the newest completed turn and does not backfill older missed Plans. - -## Interfaces and Dependencies - -The managed hook set adds `SessionEnd`. Repository Plan capture always adds a central discovery record and can add specification siblings. No public command or dependency is added. The version changes from `0.19.0` to `0.19.1`. - -## Outcomes - -The accepted Plan from this chat is now exact and discoverable in both required locations. The installed toolkit captures a real Codex Plan during the following prompt hook. Doctor reports version `0.19.1` ready. - -The full review was clean. A later test-only delta corrected the app-server capability and observation boundary. Its delta review was also clean. - -The final installer delta gives `SessionEnd` its documented 3-second maximum through one shared timeout owner. Its review was clean. Live installation, Doctor, and a fresh Codex app-server startup passed without the clamp warning. diff --git a/docs/plans/cpk-041-implementation-aware-decisions.md b/docs/plans/cpk-041-implementation-aware-decisions.md deleted file mode 100644 index 49d66a3..0000000 --- a/docs/plans/cpk-041-implementation-aware-decisions.md +++ /dev/null @@ -1,78 +0,0 @@ -# Explain code consequences before decisions - -This ExecPlan is a living document until review closure. Maintain it according to `.agent/PLANS.md`. - -## Purpose - -Before a material code choice, Codex must explain each option in plain language. The user must see the visible result and the implementation shape before the choice widget appears. - -## Progress - -- [x] (2026-08-22) Reconciled the accepted CPK-041 Plan with CPK-008 and CPK-040. -- [x] (2026-08-22) Created branch `cpk-041-implementation-aware-decisions` from reviewed commit `982321ef930b58c366c856c2504912a7bf3da7ea`. -- [x] (2026-08-22) Made CPK-041 the only Active roadmap task. -- [x] (2026-08-22) Strengthened the decision owner and routed Design Preflight choices through it. -- [x] (2026-08-22) Passed the focused checks and all 80 default Python checks. -- [x] (2026-08-22) Corrected the pass 1 scope mismatch so all material technical choices use the implementation brief. -- [x] (2026-08-22) Completed review, live installation, Doctor, and the clean-session decision smoke test. - -## Prior Plan Reconciliation - -Record: `.agent/plan-history/plan-summary.20260822T065923051937Z.4415ee79c8b0327ba824768113192b4f60662d355fb4931876ec995a214a5526.md` - -Status: carried - -Reason: This record is the accepted CPK-041 implementation contract. - -CPK-008 remains authoritative for the material-choice trigger, fixed labels, and routine-question exclusions. CPK-041 strengthens its incomplete option-effect rule. CPK-040 remains authoritative for Plan capture and does not conflict. - -## Product Boundary - -Apply [Scope boundaries](../../assets/skills/design-preflight/references/scope-boundaries.md). This task composes the decision-handoff owner and the Design Preflight route. The Simple English skill is an opaque wording owner. The Codex choice widget is an opaque display owner with short question and option fields. - -The supported model is a material technical choice in a normal Codex task with readable repository source. Routine preferences, discoverable facts, line-count estimates, new skills, model evaluation infrastructure, and changes to the choice widget are excluded. - -## Normal-Use Behavior Floor - -Codex inspects the implementation paths before it asks. Each practical option explains the visible result, code change, source anchor, new moving parts, and test or maintenance effects. Plain language comes before a source name. - -The complete brief appears before `request_user_input`. The widget only collects the selected option. If source cannot prove an impact, the brief states `unknown` and names the missing evidence. - -After the user selects an option, Codex records the selected behavior and implementation shape in the active ExecPlan. - -## Scope Ceiling - -Do not add a skill, response generator, parser, line estimator, telemetry, service, or model-evaluation harness. Do not modify the upstream Simple English skill. Do not expand the full handoff to routine questions. - -## Scenario Proof - -| Scenario | Discriminator | Contrast | Production path | Required oracle | Runnable check | Result | -| --- | --- | --- | --- | --- | --- | --- | -| Material code choice | Choice changes architecture or state | routine preference | Design Preflight to decision owner | complete source-backed brief before widget | `test_material_code_decisions_explain_implementation_before_choice` | Passed | -| Option impact | existing-function extension | new state or subsystem | repository inspection to option facts | visible result and exact implementation shape differ | focused decision-owner assertions | Passed | -| Source anchor | plain role plus source name | source jargon alone | option brief | plain role appears before file or symbol | focused decision-owner assertions | Passed | -| Unknown impact | source does not prove a consequence | supported consequence is known | inspection to decision brief | `unknown` names missing evidence | focused decision-owner assertions | Passed | -| Tool boundary | complete brief before widget | widget-only explanation | handoff to `request_user_input` | widget only collects the answer | focused decision-owner assertions | Passed | -| Selected decision | user selects an option | no selection yet | choice result to active ExecPlan | behavior and implementation shape are durable | focused decision-owner assertions | Passed | - -## Plan of Work - -Keep `decision-handoffs.md` as the single owner. Require Simple English for the brief and widget. Define the five option facts and structural cost terms. Require repository inspection, explicit unknowns, a complete pre-widget brief, and durable selection recording. - -Add a focused route from Design Preflight to the decision owner. Update the existing rule tests and version from `0.19.1` to `0.20.0`. Update only documentation that becomes wrong. - -## Validation and Acceptance - -Run focused rule tests, the full suite, Python compilation, shell syntax checks, link and owner checks, manifest checks, and `git diff --check`. Finalize documentation before adversarial review. - -After clean review, install the candidate and run Doctor. Use one clean read-only Codex planning session to repeat the supplied paging decision. The result must explain code consequences before it asks for a choice. - -## Interfaces and Dependencies - -The installed decision-handoff contract gains source-backed implementation consequences. No CLI, runtime API, dependency, or persistent product state changes. The toolkit version becomes `0.20.0`. - -## Outcome - -Review found one wording gap: `material code decision` was narrower than the accepted technical-choice scope. The correction uses `material technical decision` in the guard, option rule, and selection rule. The delta and final coherence reviews were clean. - -The reviewed candidate is installed. Doctor reports `Result: ready` for version `0.20.0`. A clean read-only planning smoke explained all three paging options before the interactive-tool marker. It named visible behavior, structural changes, new state, proof, maintenance cost, and unavailable source facts. diff --git a/docs/plans/cpk-042-large-plan-checkpoints.md b/docs/plans/cpk-042-large-plan-checkpoints.md deleted file mode 100644 index 6d96067..0000000 --- a/docs/plans/cpk-042-large-plan-checkpoints.md +++ /dev/null @@ -1,103 +0,0 @@ -# Split large plans into reviewed checkpoints - -This ExecPlan is a living document until review closure. Maintain it according to `.agent/PLANS.md`. - -## Purpose - -Plan Mode must divide large work at independently verifiable boundaries. One ExecPlan keeps stable, ordered subtasks. Each completed subtask receives focused validation, review, and a local checkpoint commit. One final coherence review covers the complete task. - -## Progress - -- [x] (2026-08-23) Reconciled the accepted CPK-042 Plan with CPK-040 and CPK-041. -- [x] (2026-08-23) Created branch `cpk-042-large-plan-checkpoints` from `0013a3c0d3c777514e9315ae46b7bd17f471962e`. -- [x] (2026-08-23) Made CPK-042 the only Active roadmap task. -- [x] (2026-08-23) CP1: Added checkpoint review and delivery rules. Validation and the correction delta review passed. -- [x] (2026-08-23) CP2: Added semantic plan splitting and safe replanning. Validation, checkpoint review, live smokes, and final coherence passed. - -## Prior Plan Reconciliation - -Record: `.agent/plan-history/plan-summary.20260822T050100617085Z.fd7dfe4c94e461a1824112794d31e1372d316ccf79eed8a3937d2754c1157e40.md` - -Status: carried - -Reason: CPK-040 preserves distinct accepted Plan responses and links them to one ExecPlan. - -Record: `.agent/plan-history/plan-summary.20260822T065923051937Z.4415ee79c8b0327ba824768113192b4f60662d355fb4931876ec995a214a5526.md` - -Status: carried - -Reason: CPK-041 remains authoritative for source-backed material decisions. - -Record: `.agent/plan-history/plan-summary.20260823T052048899607Z.c539b46a7e5fa56092a382fef046fd00d4271c42c4fda8e0f0e2216ce94df122.md` - -Status: carried - -Reason: This record is the accepted CPK-042 implementation contract. - -## Product Boundary - -The ExecPlan owner defines semantic subtask boundaries. Adversarial Review owns checkpoint and coherence review behavior. Delivery Lifecycle owns local commit eligibility. Plan History owns replan reconciliation. - -The task changes installed instructions and their contract tests. It does not add runtime state, child plans, a task database, an action counter, a dependency service, or a new skill. Plan capture remains unchanged. - -## Normal-Use Behavior Floor - -A large Plan contains stable subtasks when its outcomes can be implemented and proved separately. Each subtask names its outcome, owner boundary, dependencies, implementation result, validation oracle, review boundary, and local commit boundary. - -A clean checkpoint review covers only the current subtask delta and its direct interaction with completed checkpoints. It does not close the task. One final coherence review covers the complete feature before roadmap completion. - -When Plan Mode replans unfinished work, it preserves completed identifiers, outcomes, contracts, and commits. A change to completed behavior becomes a new corrective subtask. - -## Scope Ceiling - -Use semantic boundaries only. Do not add a numeric action ceiling. Do not split one atomic migration or stateful sequence that needs one proof boundary. Do not create child ExecPlans or mutable task infrastructure. - -## Subtasks - -### CP1 — Reviewed-subtask delivery - -Observable outcome: A completed subtask can receive a scope-bound checkpoint review and local commit without closing the task. - -Primary owner and change boundary: Adversarial Review owns `checkpoint` mode and its packet. Delivery Lifecycle only consumes the clean checkpoint result to allow a local commit. - -Dependencies: Existing `full`, `delta`, and `coherence` review modes; existing task-wide production-defect accounting. - -Implementation result: Adversarial Review now defines `checkpoint` mode. Its packet records the subtask and previous accepted checkpoint. Delivery Lifecycle permits the reviewed local commit without closing the task. - -Validation and oracle: The focused checkpoint-rule test passed. All 80 default Python checks passed, with one native Windows skip. Shell syntax and `git diff --check` passed. - -Review result: Pass 1 found that a corrected checkpoint had no commit path after its clean delta review. The correction makes that delta the clean checkpoint result. The focused delta review was clean. - -Checkpoint boundary: Review the staged CP1 tree with the existing full-review workflow. Commit locally only after a clean result. - -### CP2 — Semantic splitting and safe replanning - -Observable outcome: Plan Mode produces one ExecPlan with stable semantic subtasks and preserves completed checkpoints during replanning. - -Primary owner and change boundary: `.agent/PLANS.md` owns subtask structure. Plan History owns replan reconciliation. Tests and version metadata prove installation. - -Dependencies: CP1 checkpoint review and commit rules. - -Implementation result: `.agent/PLANS.md` defines semantic split triggers, stable subtask facts, and checkpoint proof boundaries. Plan History preserves completed checkpoints and scopes replans to unfinished work. The toolkit version is `0.21.0`. - -Validation and oracle: The focused plan, history, owner, and version checks passed. All 81 default checks passed, with one native Windows skip. Shell syntax and `git diff --check` passed. The live install used version `0.21.0`, and Doctor reported `Result: ready`. The first planning smoke produced one checkpointed ExecPlan. The clean replan smoke preserved the completed checkpoint, scoped supersession to unfinished work, and added a corrective subtask. - -Checkpoint review result: Clean. The reviewer checked CP2 against commit `1200a8d2622ba4bf418ec7b7bdd03adf60012f8d` and found no defects. - -Coherence result: The coherence pass found that two lifecycle consumers could treat an intermediate checkpoint as final. Docs Maintainer and Roadmap Maintainer now require Adversarial Review's final clean result. The correction delta review was clean. - -Checkpoint boundary: Review CP2 against the accepted CP1 commit. After it passes, run one cumulative coherence review from the task base. Close the task and commit locally only after both reviews pass. - -## Validation and Acceptance - -Keep detailed output in one ignored CPK-042 test-result file. Finalize substantive documentation before each review. Keep the roadmap Active after CP1. Move it to Completed only after final coherence passes. - -## Interfaces and Dependencies - -The review mode enum gains `checkpoint`. Its packet gains the subtask identifier and previous accepted checkpoint. The toolkit version becomes `0.21.0`. No dependency changes. - -## Outcome - -Version `0.21.0` splits large Plans at semantic proof boundaries. Stable subtasks receive focused review and local checkpoints. Replanning preserves completed work and changes only the unfinished tail. One final coherence review gates task closure. - -CP1 passed after one correction delta. CP2 passed its checkpoint review. The final coherence correction delta passed. The live planning smokes proved initial planning and completed-checkpoint replanning. diff --git a/docs/plans/cpk-043-review-gated-publication.md b/docs/plans/cpk-043-review-gated-publication.md deleted file mode 100644 index cf534dd..0000000 --- a/docs/plans/cpk-043-review-gated-publication.md +++ /dev/null @@ -1,102 +0,0 @@ -# Review PRs before hosted CI - -This ExecPlan is a living document until review closure. Maintain it according to `.agent/PLANS.md`. - -## Purpose - -PR publication must review the current head before hosted CI starts. Codex keeps the pull request draft, requests `@codex review`, and applies the normal review gates to each finding. A clean current-head review permits readiness and hosted CI. - -## Progress - -- [x] (2026-08-23) Reconciled CPK-043 with the completed CPK-040 through CPK-042 records. -- [x] (2026-08-23) Created branch `cpk-043-review-gated-publication` from `da3bb3361da35353a740d904b10a69c75e31779d`. -- [x] (2026-08-23) Made CPK-043 the only Active roadmap task. -- [x] (2026-08-23) Completed Design Preflight for the publication owner and its focused contract check. -- [x] (2026-08-23) Corrected the publication owner, focused checks, and version. -- [x] (2026-08-23) Passed the focused checks, all 82 default tests with one native Windows skip, compilation, shell syntax, and diff checks. -- [x] (2026-08-23) Completed documentation maintenance. The publication owner and this ExecPlan are the only substantive documentation changes. -- [x] (2026-08-23) Completed clean full review at staged tree `83974756aeebd1bcec086d33bd0fb1a5366b34c1`. -- [x] (2026-08-23) Completed review closure. Live installation remains untracked delivery evidence. - -## Prior Plan Reconciliation - -Record: `.agent/plan-history/plan-summary.20260822T050100617085Z.fd7dfe4c94e461a1824112794d31e1372d316ccf79eed8a3937d2754c1157e40.md` - -Status: carried - -Reason: CPK-040 remains authoritative for Plan capture and implementation handoff. - -Record: `.agent/plan-history/plan-summary.20260822T065923051937Z.4415ee79c8b0327ba824768113192b4f60662d355fb4931876ec995a214a5526.md` - -Status: carried - -Reason: CPK-041 remains authoritative for source-backed material decisions. - -Record: `.agent/plan-history/plan-summary.20260823T052048899607Z.c539b46a7e5fa56092a382fef046fd00d4271c42c4fda8e0f0e2216ce94df122.md` - -Status: carried - -Reason: CPK-042 remains complete. CPK-043 adds a new corrective task after its checkpoint commits. - -Record: `.agent/plan-history/plan-summary.20260824T031427928859Z.f30d03e6b396d05f07f5ce7eebc8b8e8b81e2b1cfe8ebc739342a6e444ca6968.md` - -Status: carried - -Reason: This record is the accepted CPK-043 implementation contract. - -## Plan Deviations - -The accepted CPK-043 marker named the task instead of a repository Markdown path. Plan History saved the record in central unlinked storage. This task copies the exact record beside this ExecPlan and keeps the central record unchanged. - -## Product Boundary - -[Publication](../../assets/skills/publication/references/publication.md) owns PR sequencing and publication gates. [Adversarial Review](../../assets/skills/adversarial-review/SKILL.md) owns finding scope, applicability, severity, and stop behavior. [Delivery Lifecycle](../../assets/skills/delivery-lifecycle/references/delivery-lifecycle.md) owns accepted corrections. - -CPK-043 composes the PR publication procedure. The completed CPK-042 checkpoint process and direct integration remain opaque. - -## Design Preflight - -Required outcome: Codex reviews the latest PR head while the PR remains draft. Hosted CI starts only after no applicable finding remains. - -Existing owner: `assets/skills/publication/references/publication.md`. - -Normal-use behavior floor: Before remote publication, Codex proves that draft work does not start hosted CI. It opens a draft, requests `@codex review`, classifies each response through Adversarial Review, and marks the PR ready only after the current head is clean. - -Scope ceiling: Do not add a workflow, parser, publication script, dispatcher, state machine, dependency, or runtime state. Do not copy the review rules into Publication. - -Applicable failures and checks: - -- The procedure marks a PR ready before a current-head draft review. A focused contract check must reject this sequence. -- A PR finding uses its raw severity before the scope gate. A focused route check must require Adversarial Review before any action. -- Protected `main` has draft-unsafe CI and the procedure falls back to direct integration. A focused contract check must require a configuration stop. -- A correction push preserves an earlier clean signal. A focused contract check must require a new draft review for the new head. - -Preflight: ready — correct the single publication owner and add one focused contract check. - -## Implementation - -Replace automatic ready-state review with an explicit draft review. Define readiness from a completed current-head review with no retained applicable findings. Treat a thumbs-up as sufficient evidence, not the only clean result. - -Route every PR finding to Adversarial Review before Publication considers severity, correction, or stop behavior. Route accepted corrections through Delivery Lifecycle. Keep detailed review rules in their current owners. - -Require a draft-safe CI configuration before publication starts. If protected `main` requires a PR but the repository cannot prove this configuration, stop before the branch push. Keep the existing latest-head CI, conversation, mergeability, squash-merge, and integration gates. - -Update the committed version from `0.21.0` to `0.21.1`. Update the focused tests and checksum manifest after content is final. - -## Validation and Acceptance - -The focused check must prove the draft review sequence, current-head reset, draft-safe CI gate, review-owner route, excluded-finding behavior, and severe-stop route. It must reject the obsolete automatic-review instruction. - -Run the focused check, full Python suite, compilation, shell syntax, `git diff --check`, and manifest validation. Keep detailed output in `.agent/test-results/cpk-043-review-gated-publication.md`. - -Finalize documentation before one fresh full review. After a final clean result, close the roadmap, update checksums, install the reviewed candidate, and require Doctor to report `Result: ready`. - -## Interfaces and Dependencies - -The installed `publish` contract gains a draft-review gate and a shared finding route. The toolkit version becomes `0.21.1`. No command, dependency, or runtime API changes. - -## Outcome - -Version `0.21.1` reviews the current PR head while the pull request remains draft. Publication scope-gates each finding before action. A clean current-head review permits readiness and hosted CI. - -Full correctness review passed with no findings at staged tree `83974756aeebd1bcec086d33bd0fb1a5366b34c1`. diff --git a/docs/plans/cpk-044-review-correction-authority.md b/docs/plans/cpk-044-review-correction-authority.md deleted file mode 100644 index 9b9c1c0..0000000 --- a/docs/plans/cpk-044-review-correction-authority.md +++ /dev/null @@ -1,135 +0,0 @@ -# Separate review findings from correction authority - -This ExecPlan is a living document until review closure. Maintain it according to `.agent/PLANS.md`. - -## Purpose / Big Picture - -Local review must discover defects without receiving the main thread's conclusions. After discovery, the toolkit must decide whether each finding changes an accepted end result and whether Codex has authority to correct it. A valid observation that does not change the end result is reported and excluded. Any correction that would add product behavior stops for human direction. Severe diagnostics must explain the problem, relevance, prevention, and required action before the detailed proof. - -## Progress - -- [x] (2026-08-24) Reconciled the accepted CPK-044 Plan with CPK-040 through CPK-043. -- [x] (2026-08-24) Created branch `cpk-044-review-correction-authority` from `28734b2623555b8a539ca0157f510111b1eeacb1`. -- [x] (2026-08-24) Made CPK-044 the only Active roadmap task. -- [x] (2026-08-24) Completed Design Preflight for the review and diagnostic instruction owners. -- [x] (2026-08-24) CP1 completed: native review discovery and correction authority passed a checkpoint review and a clean correction-delta review. -- [x] (2026-08-24) CP2 implementation completed: severe diagnostics now lead with the problem, end-result relevance, prevention, and required action. -- [x] (2026-08-24) Updated documentation, version `0.22.0`, focused tests, and the distribution manifest. -- [x] (2026-08-24) Completed the full test, compile, shell, PowerShell, manifest, Plan-history, and diff checks. -- [x] (2026-08-24) CP2 passed its native checkpoint review. -- [x] (2026-08-24) Completed the final complete-candidate review, installation, Doctor check, native-review smoke, and review closure. - -## Surprises & Discoveries - -- Observation: `codex review --commit` accepts a commit target but cannot also accept a free-form prompt. - Evidence: The planning feasibility probe rejected the combined form. A synthetic commit message is therefore the only task-intent input. -- Observation: The first native checkpoint review found two contract omissions in the new review instructions. - Evidence: Review of synthetic commit `d57f668b266a968ab408e0793f71097a5ff5d1e0` found that an undefined result could be dropped by the wrong-result scope predicate and that the P0-P2 counted-pass threshold was missing. -- Observation: The complete suite found that the native-review rewrite had dropped existing lifecycle and Scenario Proof routes. - Evidence: Four static contract tests failed. Restoring the prior route links and lifecycle phrase made all 83 tests pass, with one platform-specific skip. -- Observation: The final native review challenged broad publication authority and found a real rule-owner conflict for contract gaps. - Evidence: Broad `publish` authority does not override CPK-044's required finding decision, so that observation was excluded. The contract-gap exception moved to the canonical scope owner. - -## Decision Log - -- Decision: Use an unreferenced synthetic commit for each local review target. - Rationale: Native Codex review can inspect an exact staged tree without creating a branch reference or changing tracked files. - Date/Author: 2026-08-24, user and Codex. -- Decision: Treat every finding source as untrusted input to one correction-authority gate. - Rationale: Reviewer severity and fix suggestions do not define product scope or grant implementation authority. - Date/Author: 2026-08-24, user and Codex. -- Decision: Replace the limited coherence pass with a complete final review. - Rationale: One final native review checks the full current candidate after checkpoint and delta reviews. - Date/Author: 2026-08-24, user and Codex. - -## Outcomes & Retrospective - -Version `0.22.0` now uses native review for exact staged candidates. One source-independent gate excludes findings that do not change the accepted result and permits only direct repairs without human direction. Severe diagnostics now lead with the problem, end-result relevance, prevention, and required action. All 83 tests passed, with one Windows-only skip. The installed candidate passed Doctor, the native-review smoke, correction-delta review, and final complete-candidate review. - -## Prior Plan Reconciliation - -Record: `.agent/plan-history/plan-summary.20260822T050100617085Z.fd7dfe4c94e461a1824112794d31e1372d316ccf79eed8a3937d2754c1157e40.md` - -Status: carried - -Reason: CPK-040 remains authoritative for Plan capture and implementation handoff. - -Record: `.agent/plan-history/plan-summary.20260822T065923051937Z.4415ee79c8b0327ba824768113192b4f60662d355fb4931876ec995a214a5526.md` - -Status: carried - -Reason: CPK-041 remains authoritative for source-backed material decisions. - -Record: `.agent/plan-history/plan-summary.20260823T052048899607Z.c539b46a7e5fa56092a382fef046fd00d4271c42c4fda8e0f0e2216ce94df122.md` - -Status: carried - -Reason: CPK-042 checkpoint and delta review remain authoritative. CPK-044 supersedes only its limited coherence pass with final review. - -Record: `.agent/plan-history/plan-summary.20260824T031427928859Z.f30d03e6b396d05f07f5ce7eebc8b8e8b81e2b1cfe8ebc739342a6e444ca6968.md` - -Status: carried - -Reason: CPK-043 PR sequencing remains authoritative. Its findings now use the source-independent gate. - -Record: `.agent/plan-history/plan-summary.20260824T135017227348Z.7cfbec79d5ce39f1a1d436a31dccfe0669c616f252b6793d4b90dc2b34ad13d6.md` - -Status: carried - -Reason: This record is the accepted CPK-044 implementation contract. - -## Plan Deviations - -Plan History first used unlinked storage because this ExecPlan did not exist when the Plan was captured. The exact record is copied beside this file. The central record remains unchanged. - -## Context and Orientation - -`assets/skills/adversarial-review/SKILL.md` owns local review, finding validation, correction, and stop behavior. Its references define the native review target, adjudication record, and review lenses. `assets/skills/defect-diagnostic/SKILL.md` owns severe defect reconstruction. Its diagnostic template owns the human-facing order. `tests/test_kit.py` enforces these instruction contracts. `kit.py` owns the toolkit version. `MANIFEST.sha256` records distributed file checksums. - -## Product Boundary - -[Scope boundaries](../../assets/skills/design-preflight/references/scope-boundaries.md) limits review to accepted product behavior. CPK-044 composes Adversarial Review and Defect Diagnostic. Delivery Lifecycle, Design Preflight, Publication, and the existing three-pass breaker are opaque and must retain their documented behavior. No owner is promoted from deferred work. - -The authoritative product source is the accepted CPK-044 Plan and the user's instruction that review corrections must not add features, scope, assumptions, policy, state, interfaces, dependencies, fallbacks, or lifecycle behavior. - -## Design Preflight - -Required outcome: Native Codex review discovers candidate defects independently. The coordinator then excludes observations that leave the accepted result correct, stops on undefined results, and automatically applies only a direct repair that restores an existing result in its clear owner. - -Existing owners: `assets/skills/adversarial-review/SKILL.md` owns the review gate. `assets/skills/defect-diagnostic/references/diagnostic-summary.md` owns diagnostic presentation. - -Normal-use behavior floor: Every source uses the same gate. Severity is considered only after relevance, scope, and supported use are proven. A mixed set that contains one decision-required correction produces no partial edits. Native review targets the exact staged tree and its mode-specific parent. Native failure stops without a generic fallback. Severe diagnostics keep full proof but show the plain summary first. - -Scope ceiling: Add no parser, daemon, service, dependency, telemetry, model evaluation, recovery behavior, or duplicate rule owner. Do not preload exclusions, scenario conclusions, or correction directions into native discovery. Do not claim that local and hosted Codex review use the same model or internal prompt. - -Preflight: ready — revise the two existing instruction owners and add focused static contract checks. - -## Plan of Work - -CP1 changes `assets/skills/adversarial-review/SKILL.md` and its focused references. Stage the complete checkpoint. Create an unreferenced commit from that staged tree with only accepted intent and source in its message. Run `codex review --commit` against that commit. After a clean checkpoint review, create the planned local checkpoint commit. - -CP2 changes the severe diagnostic owner and template. It also finalizes this ExecPlan, the roadmap, tests, version `0.22.0`, and the manifest. Run focused and complete validation. Review the complete candidate from the task base in `final` mode. Install that reviewed candidate, require Doctor to report ready, and run one opt-in native-review smoke before review closure and the second checkpoint commit. - -## Concrete Steps - -Work from `/home/mbeutler/Projects/codex-practical-kit`. Use `python3 -m unittest tests.test_kit` for the complete suite, `python3 -m py_compile` for Python sources, `bash -n` for shell scripts, and PowerShell parser checks when `pwsh` is available. Use `git diff --check` and the repository manifest check. Keep detailed output in `.agent/test-results/cpk-044-review-correction-authority.md`. - -For each native review, record the staged tree before and after the command. Require no unstaged tracked changes. Stop if `codex review` fails. Do not use a generic reviewer as fallback. - -## Validation and Acceptance - -Focused tests must prove the source-independent gate, direct-repair limit, atomic mixed-finding stop, irrelevant-finding exclusion, contract-gap stop, severe diagnostic trigger, exact native targets and parents, native failure stop, final full review, and diagnostic summary order. The complete suite must pass. Python, shell, PowerShell, rule-owner, link, manifest, and diff checks must pass. - -Acceptance also requires one native-review smoke against a temporary synthetic commit. The staged tree and tracked worktree must be unchanged after that command. The installed reviewed candidate must make Doctor report `Result: ready`. - -## Idempotence and Recovery - -Read-only checks can be repeated. Synthetic commits are unreferenced and do not change a branch. If any required command fails, stop and report the error. Do not add fallback or recovery behavior. - -## Artifacts and Notes - -Preserve `.mcp.json`, `.repowise/`, `.vscode/`, and ignored test results. Do not stage them. Local checkpoint commits do not authorize publication. - -## Interfaces and Dependencies - -The installed Adversarial Review contract now invokes the existing `codex review --commit` command. No new command, script, parser, service, dependency, or runtime API is added. The toolkit version becomes `0.22.0`. diff --git a/docs/plans/cpk-045-boundary-trace-closure.md b/docs/plans/cpk-045-boundary-trace-closure.md deleted file mode 100644 index ada6dad..0000000 --- a/docs/plans/cpk-045-boundary-trace-closure.md +++ /dev/null @@ -1,201 +0,0 @@ -# Close Every Behavioral Boundary - -This ExecPlan is a living specification until review closure. Maintain it according to `.agent/PLANS.md`. - -## Purpose / Big Picture - -Implementation can preserve the common case while it violates an explicit boundary. A positive-only test can then pass. After this change, Design Preflight must inventory each explicit behavioral boundary before implementation. A fresh verifier must inspect the implementation and paired proof before native review starts. - -The release version is `0.23.0`. Work occurs on branch `cpk-045-boundary-trace-closure` from commit `388b23fc165df788848d19e6ce738a973f888d2e`. - -## Surprises & Discoveries - -- Observation: The accepted Plan initially used unlinked storage because this specification did not exist. - Evidence: `.agent/plan-history/plan-summary.20260824T164719361941Z.f1479c9effab9071b8ccaa86dce1dbee407b79647c6bb7d542aea8c75caae32b.md` contains the exact Plan. -- Observation: Current Scenario Proof starts with retained scenarios. It has no independent denominator for omitted source boundaries. - Evidence: `assets/skills/design-preflight/references/preflight-review.md` records scenarios but no disposition for each source clause. -- Observation: A fresh challenger derived both mapping states and rejected the broader helper from only the raw requirement. - Evidence: The clean-context result classified the helper as opaque and stated that the positive-only check proves only the unmapped side. - -## Decision Log - -- Decision: Extend Scenario Discrimination and Design Preflight. Do not add a skill or executable framework. - Rationale: These files already own requirement-derived contrasts and the pre-review proof mapping. -- Decision: A changed behavioral boundary always requires inventory and closure. - Rationale: The user selected complete boundary tracing. A direct bug that changes no boundary retains the small-change exception. -- Decision: Use one fresh read-only verifier immediately before native review. - Rationale: The verifier independently reconstructs the source denominator and inspects actual production and test paths. -- Decision: Do not provide the trace record to native review. - Rationale: Native review remains an independent defect-discovery lens. -- Decision: Replace the preflight card's numeric line cap with a compactness rule. - Rationale: Multiple mandatory boundary and scenario rows cannot fit under the old limit. Required proof rows take priority. -- Decision: Keep mutable progress and lifecycle state out of tracked files except `docs/roadmap.md`. - Rationale: The roadmap is the human progress view. ExecPlans are stable implementation specifications, not status ledgers. - -## Outcomes & Retrospective - -The toolkit requires source-complete boundary proof before native review. ExecPlans retain stable decisions and checks without duplicating roadmap progress or operational results. - -## Context and Orientation - -`assets/skills/design-preflight/SKILL.md` owns preflight sequencing. `assets/skills/design-preflight/references/scenario-discrimination.md` owns requirement-derived discriminators and paired contrasts. `preflight-card.md` defines the coordinator's planning record. `preflight-review.md` defines the read-only challenger interfaces. `assets/skills/adversarial-review/SKILL.md` owns native review sequencing. `tests/test_kit.py` verifies rule ownership and route contracts. `kit.py` owns the version. `MANIFEST.sha256` records distributed files. - -A behavioral boundary is an explicit requirement that limits, selects, excludes, relates, or preserves an outcome. Trace closure is a fresh read-only check that compares every authoritative source boundary with the implemented paths and direct tests. - -Applicable immutable Plan records: - -- `.agent/plan-history/plan-summary.20260822T050100617085Z.fd7dfe4c94e461a1824112794d31e1372d316ccf79eed8a3937d2754c1157e40.md` -- `.agent/plan-history/plan-summary.20260822T065923051937Z.4415ee79c8b0327ba824768113192b4f60662d355fb4931876ec995a214a5526.md` -- `.agent/plan-history/plan-summary.20260823T052048899607Z.c539b46a7e5fa56092a382fef046fd00d4271c42c4fda8e0f0e2216ce94df122.md` -- `.agent/plan-history/plan-summary.20260824T031427928859Z.f30d03e6b396d05f07f5ce7eebc8b8e8b81e2b1cfe8ebc739342a6e444ca6968.md` -- `.agent/plan-history/plan-summary.20260824T135017227348Z.7cfbec79d5ce39f1a1d436a31dccfe0669c616f252b6793d4b90dc2b34ad13d6.md` -- `.agent/plan-history/plan-summary.20260824T164719361941Z.f1479c9effab9071b8ccaa86dce1dbee407b79647c6bb7d542aea8c75caae32b.md` - -## Product Boundary - -[Scope boundaries](../../assets/skills/design-preflight/references/scope-boundaries.md) limits this task to accepted implementation and test proof. The authoritative sources are the accepted CPK-045 Plan, the requirement that every explicit behavioral boundary receives trace proof, and the user's rule that only the roadmap stores tracked progress and lifecycle state. - -Design Preflight, Scenario Discrimination, and the pre-review gate are `composes` owners. Native review, review correction authority, Plan capture, publication, and the supported operating model are `opaque`. No deferred owner is promoted. - -The scope ceiling excludes a parser, coverage percentage, mutation system, formal property language, daemon, dependency, semantic-ranking service, post-failure recovery system, or duplicate rule owner. - -## Design Preflight - -Required outcome: Every in-scope behavioral boundary receives a source disposition before implementation. A fresh verifier must prove each applicable path and paired test before native review. - -Existing owner: Scenario Discrimination owns the boundary trace. Design Preflight invokes it. The preflight card and review result store task-specific records. Adversarial Review invokes the completed closure gate before native discovery. - -Normal-use behavior floor: Source clauses cannot disappear because they resemble earlier clauses. Equal-result invariants remain boundaries. Every applicable entry point receives proof. Positive-only tests, component tests, unrelated fixture changes, and broader helpers cannot close the trace. - -## Boundary Inventory - -| Boundary | Source | Condition or invariant | Required sides and oracle | Entry points | Scenario Proof | -| --- | --- | --- | --- | --- | --- | -| B1 | Accepted CPK-045 Plan, CP1 | Every authoritative clause that defines a behavioral boundary receives a disposition. | Mapped clauses enter the trace. Non-boundary, opaque, deferred, and contract-gap clauses retain an explicit disposition. An omitted later clause blocks work. | Design Preflight before implementation and accepted boundary corrections. | S1 source list with duplicate-looking prefix and later distinct clause. | -| B2 | Accepted CPK-045 Plan, CP1 | Each boundary covers every applicable production path. | One scenario per path, or one composed scenario that proves all paths. Equal-result invariants use the nearest wrong meaning as the contrast. | Design Preflight before initial implementation and before accepted boundary corrections. | S2 mapped and unmapped staging paths. S3 equal-result invariant. | -| B3 | Accepted CPK-045 Plan, CP2; final review corrections | After implementation and final substantive documentation, one fresh read-only verifier independently enumerates source boundaries before it sees accepted `B#` records. Trace scope matches native-review scope. | Phase 1 receives only raw requirements and the exact review boundary. Phase 2 receives the accepted inventory, Scenario Proof, diff, production source, and named tests. Checkpoints exclude later unimplemented subtasks. Full and final reviews require the complete task inventory. | Full, checkpoint, delta, and final review candidates with a boundary inventory. | S4 positive-only failure. S5 unrelated fixture failure. S6 broader-helper failure. S10 verifier order, inputs, and review boundary. | -| B4 | Accepted CPK-045 Plan, CP2 | Closure evidence remains valid only for the exact traced candidate. | A change to requirement sources, boundary records, production paths, or named tests invalidates closure. An unrelated document change does not. | Candidate preparation immediately before native review. | S7 traced change invalidates. S8 unrelated document keeps closure. | -| B5 | User decision in the accepted Plan | A new or changed behavioral boundary cannot use the small-change exception. | Boundary change requires inventory and closure. A direct arithmetic bug with no boundary change retains the exception. | Initial work and accepted review corrections. | S9 boundary change and direct arithmetic contrast. | -| B6 | Accepted CPK-045 Plan, CP2 | Native review remains independent from trace closure. | Native review receives the accepted intent, source, and synthetic commit. Giving it the trace record or coordinator conclusions violates the boundary. | Every native full, checkpoint, delta, and final review after trace closure. | S11 independent native-review input. | -| B7 | User corrections on 2026-08-24 | Only `docs/roadmap.md` stores tracked progress or lifecycle state. | ExecPlans store stable specification content. Operational progress, test results, review results, checkpoint state, and delivery state can stay in untracked or ignored working files. | New, resumed, and Spec Kit ExecPlans; Scenario Proof; checkpoints; review closure; delivery; completed history. | S12 tracked status versus stable specification. | - -The immutable Plan record and its byte-identical sibling copy contain one semantic clause set. Each clause has this disposition: - -| Source clause | Disposition | Boundary or reason | -| --- | --- | --- | -| Summary: the existing design is correct | non-boundary | Accepted premise. | -| Summary: existing enforcement is incomplete | non-boundary | Problem context. | -| Summary: Scenario Proof has no denominator | mapped | B1. | -| Summary: no post-implementation conformance gate | mapped | B3 and B4. | -| Version and branch | non-boundary | Delivery metadata. | -| Research: use an external boundary trace with an evidence gate | mapped | B1 and B3. | -| Research: surveyed traceability, evidence gates, executable properties, and intent-driven regression | non-boundary | Source evidence for the selected mechanism. | -| Research: exclude semantic ranking, formal properties, mutation tooling, and recovery machinery | opaque | Scope ceiling; no product behavior. | -| Research: ExecPlans do not supply a boundary-trace gate | non-boundary | Ownership context. | -| Research: the toolkit owns the missing gate | mapped | B3. | -| CP1: extend Scenario Discrimination; add no skill or durable plan | opaque | Ownership and implementation ceiling. | -| CP1: enumerate every limiting, selecting, excluding, relating, or preserving requirement | mapped | B1. | -| CP1: stable `B#` identifiers | mapped | B1. | -| CP1: record source, condition, sides, oracles, entry points, and scenarios | mapped | B1 and B2. | -| CP1: classify every relevant source clause | mapped | B1. | -| CP1: inspect the complete set despite duplicate-looking clauses | mapped | B1. | -| CP1: prove every distinct production path | mapped | B2. | -| CP1: preserve equal-result invariants with the nearest wrong contrast | mapped | B2. | -| CP1: boundary changes override the small-change exception | mapped | B5. | -| CP1: store the inventory in the card, Phase 1 result, and ExecPlan | mapped | B1. | -| CP2: run one fresh read-only verifier after implementation and final documentation | mapped | B3. | -| CP2: give all named inputs and enumerate independently before `B#` comparison | mapped | B3. | -| Final review F1: freeze independent derivation before accepted inventory disclosure | mapped | B3 and S10. | -| Final review F2: match trace scope to full, checkpoint, delta, and final review scope | mapped | B3 and S10. | -| CP2: return the specified result shape | mapped | B3 and B4. | -| CP2: false, unknown, missing, or unsupported evidence blocks review | mapped | B3. | -| CP2: inspect test bodies and reject positive, component, aggregate, and writer evidence | mapped | B3. | -| CP2: run immediately before review and invalidate traced changes | mapped | B4. | -| CP2: do not send the trace record to native review | mapped | B6. | -| Test Plan: every authoritative clause receives a disposition | mapped | B1 and S1. | -| Test Plan: later distinct clauses survive duplicate-looking clauses | mapped | B1 and S1. | -| Test Plan: mapped and unmapped staging outcomes | mapped | B2 and S2. | -| Test Plan: equal-result invariants remain boundaries | mapped | B2 and S3. | -| Test Plan: every applicable entry point receives proof | mapped | B2 and S2. | -| Test Plan: positive-only evidence blocks review | mapped | B3 and S4. | -| Test Plan: fixtures isolate the discriminator from unrelated gates | mapped | B3 and S5. | -| Test Plan: broader helpers fail sensitivity | mapped | B3 and S6. | -| Test Plan: traced documentation or implementation changes invalidate closure | mapped | B4 and S7. | -| Test Plan: arithmetic repair without a boundary change retains the exception | mapped | B5 and S9. | -| Test Plan: clean-context proof derives both staging cases and rejects weak evidence | mapped | B2 and B3; S2, S4, S6, and S11. | -| Test Plan: complete toolkit validation | non-boundary | Delivery validation. | -| Test Plan: use reviewed CP1 and CP2 checkpoints and one final review | non-boundary | Delivery sequencing. | -| Test Plan: install the reviewed candidate and require Doctor ready | non-boundary | Delivery validation. | -| Assumptions: no formal completeness, parser, or coverage percentage | opaque | Explicit mechanism ceiling. | -| Assumptions: the fresh verifier is the semantic gate | mapped | B3. | -| Assumptions: documentation is final first | mapped | B3. | -| Assumptions: Review Closure changes invalidate only traced sources | mapped | B4. | -| Assumptions: roadmap state and no publication | non-boundary | Coordination and delivery state. | -| Prior Plan Reconciliation | non-boundary | Preserves earlier owners without changing them. | -| User correction: the roadmap is the sole tracked progress exception | mapped | B7 and S12. | -| User correction: ExecPlans contain stable specification content, not timestamps, flags, or current-state summaries | mapped | B7 and S12. | -| User correction: test, review, checkpoint, and delivery results remain untracked | mapped | B7 and S12. | -| User clarification: untracked or ignored working files can record progress | mapped | B7 and S12. | -| User correction: Review Closure cannot write status into an ExecPlan | mapped | B7 and S12. | -| User correction: resumption combines the specification with Plan history, roadmap, Git, ignored results, and conversation | mapped | B7 and S12. | -| User correction: completed historical plans remain immutable | mapped | B7 and S12. | -| Optional Spec Kit: ExecPlans store stable decisions and the roadmap stores lifecycle state | mapped | B7 and S12. | - -No clause is deferred or a contract gap. - -## Scenario Proof - -[Scenario discrimination](../../assets/skills/design-preflight/references/scenario-discrimination.md), [Owner composition](../../assets/skills/design-preflight/references/owner-composition.md), and [Full-set results](../../assets/skills/design-preflight/references/full-set-results.md) control this proof. - -| Scenario | Discriminator | Contrast | Production path | Required oracle | Runnable test or command | -| --- | --- | --- | --- | --- | --- | -| S1 | Source-clause identity | Two similar clauses followed by one distinct boundary | Raw sources to inventory to disposition | Every clause has one disposition and omission blocks work | Clean-context command from S2 and `test_preflight_inventories_every_behavioral_boundary` | -| S2 | Mapped-plan status | Same staging input with mapped and unmapped base plans | Requirement to both production entry paths | Only the required path substitutes the plan | `codex exec --ephemeral --sandbox read-only -C . -o .agent/test-results/cpk045-forward-output.json - < tests/fixtures/cpk045-boundary-forward.md` | -| S3 | Preserved invariant | Both correct sides have the same terminal result but the nearest wrong meaning differs | Requirement to implementation and terminal owner | The invariant holds on both sides | Clean-context command from S2 and `test_preflight_inventories_every_behavioral_boundary` | -| S4 | Executed boundary side | Positive-only check versus paired check | Test body to terminal oracle | Positive-only evidence blocks review | `test_boundary_trace_closure_blocks_native_review` | -| S5 | Fixture isolation | Discriminator-only fixture versus discriminator plus unrelated gate | Test body to production predicates | Unrelated variation blocks review | Clean-context command from S2 and `test_boundary_trace_closure_blocks_native_review` | -| S6 | Enforcement meaning | Exact boundary owner versus broader helper | Entry point through gates to terminal owner | Broader meaning fails sensitivity | Clean-context command from S2 and `test_boundary_trace_closure_blocks_native_review` | -| S7 | Traced-source identity | Same candidate versus changed requirement, path, record, or named test | Final docs and source to closure evidence | A traced change invalidates closure | Clean-context command from S2 and `test_boundary_trace_closure_blocks_native_review` | -| S8 | Change relevance | Traced change versus unrelated documentation change | Candidate diff to closure evidence | Unrelated documentation does not invalidate closure | Clean-context command from S2 and `test_boundary_trace_closure_blocks_native_review` | -| S9 | Change type | Boundary change versus arithmetic repair with no boundary change | Design Preflight entry gate | Only the boundary change overrides the exception | Clean-context command from S2 and `test_preflight_inventories_every_behavioral_boundary` | -| S10 | Trace preparation and scope | Two-phase derivation before comparison versus anchored input; checkpoint-local closure versus future-subtask blocking; complete final closure versus reused checkpoint closure | Exact review boundary to independent inventory, then accepted records and candidate evidence | Only ordered, review-mode-aligned closure passes | Clean-context command from S2 and `test_boundary_trace_closure_blocks_native_review` | -| S11 | Evidence and review independence | Paired terminal proof and source-only native input versus component, aggregate, writer, or trace-primed evidence | Trace gate to native-review input | Weak evidence blocks closure; the trace record stays out of native review | Clean-context command from S2 and `test_boundary_trace_closure_blocks_native_review` | -| S12 | Tracked content purpose | Stable specification, complete resumption sources, and untracked delivery evidence versus ExecPlan status, missing resumption evidence, or tracked delivery status | Planning, resumption, checkpoints, review closure, and delivery | Only the roadmap has tracked lifecycle state; every resumption source is read; delivery evidence stays untracked | Clean-context command from S2 and `test_tracked_task_records_freeze_before_delivery` | - -## Plan of Work - -CP1 extends the Scenario Discrimination owner, the Design Preflight entry gate, the preflight card, and Phase 1 result. It adds the source disposition and boundary inventory without a second artifact. Focused tests verify clause completeness, duplicate-looking prefixes, equal-result invariants, all entry points, and the small-change rule. Review this checkpoint and create its local commit. - -CP2 adds the fresh trace-closure result to `preflight-review.md` and makes Design Preflight run it after final documentation and before Adversarial Review. Adversarial Review links to this gate before native discovery. Focused tests verify evidence quality, invalidation, and review independence. Update `kit.py` to `0.23.0`, update product documentation only when the diff makes it inaccurate, and regenerate `MANIFEST.sha256`. Review this checkpoint, then run final review from the task base. - -The final review correction separates independent inventory derivation from informed comparison. It also aligns trace scope with the existing full, checkpoint, delta, and final review boundaries. - -The accepted process correction removes operational progress and results from tracked ExecPlans, Scenario Proof, and Review Closure. It keeps `docs/roadmap.md` as the sole tracked lifecycle view and keeps detailed evidence in the ignored task result. - -## Concrete Steps - -Work from `/home/mbeutler/Projects/codex-practical-kit`. Run focused tests with `python3 -m unittest tests.test_kit.IntegrationTests.`. Run the complete suite with `./run-tests.sh`. Compile Python with the existing test launcher. Parse shell and PowerShell scripts with the existing checks. Run `git diff --check`. Record detailed output in `.agent/test-results/cpk-045-boundary-trace-closure.md`. - -Before each review, stage the complete checkpoint and require no unstaged tracked changes. Run the trace-closure verifier for the exact candidate. Then run native `codex review` with the mode and parent required by Adversarial Review. Keep its input independent from the trace record. - -## Validation and Acceptance - -Focused checks must prove B1 through B7 and S1 through S12. The clean-context forward check must derive both mapped and unmapped cases from the supplied broader-helper defect. It must reject the broader implementation, positive-only proof, component proof, aggregate result, writer report, anchored trace input, future-subtask checkpoint blocking, checkpoint-limited final closure, and tracked ExecPlan status. It must also prove two-phase trace ordering, review-mode scope, named inputs, native-review independence, and roadmap-only lifecycle state. - -The full toolkit suite, Python compilation, shell checks, PowerShell parsing, rule-owner checks, link checks, manifest validation, and `git diff --check` must pass. After final review, install the candidate with `python3 kit.py install --repo .`. Then run `python3 kit.py doctor --repo .` and require `Result: ready`. - -## Idempotence and Recovery - -Read-only checks can be repeated. Synthetic review commits do not change the branch. If a required command fails, stop and report the error. Do not add recovery behavior. - -## Artifacts and Notes - -Preserve `.mcp.json`, `.repowise/`, `.vscode/`, and ignored test results. Do not stage them. Local checkpoint commits do not authorize publication. - -## Interfaces and Dependencies - -The existing preflight card gains a boundary inventory and loses its operational result column. The existing Phase 1 JSON gains source dispositions and boundary records. `preflight-review.md` gains the `boundary-trace-closure` result. ExecPlans keep stable specifications while the roadmap owns tracked lifecycle state. No executable API or dependency is added. - -## Prior Plan Reconciliation - -CPK-040 through CPK-044 are carried. CPK-022, CPK-028, CPK-034, and CPK-035 remain authoritative. CPK-045 adds source completeness and post-implementation closure without changing their accepted behavior. diff --git a/docs/plans/cpk-046-repowise-worktree-recovery.md b/docs/plans/cpk-046-repowise-worktree-recovery.md deleted file mode 100644 index 4ebcada..0000000 --- a/docs/plans/cpk-046-repowise-worktree-recovery.md +++ /dev/null @@ -1,98 +0,0 @@ -# Recover RepoWise Worktree Support - -This ExecPlan is a living specification until review closure. Maintain it according to `.agent/PLANS.md`. - -## Purpose / Big Picture - -A Codex session in another repository tried to repair this toolkit without user authority. The rejected repair also replaced RepoWise’s linked-worktree model with duplicate primary-checkout logic. This change keeps repository scope explicit and uses RepoWise’s native worktree support. - -The release version is `0.23.1`. Work occurs on branch `cpk-046-repowise-worktree-recovery` from commit `8a0b82e54dcefa5780c4869d8412e7b4158f2659`. - -## Surprises & Discoveries - -- The rejected branch contained no commit and never changed the live installation or remote branch. -- RepoWise `0.45.0` supports linked worktrees and resolves their shared hook directory through Git. -- A linked-worktree hook is shared. Removing it from one linked worktree would disable maintenance for its siblings. -- The accepted Plan initially used unlinked storage because this specification did not exist. - -## Decision Log - -- Preserve `8a0b82e` as valid repository-local work. -- Delete the rejected custom worktree resolver and rely on RepoWise `0.45.0`. -- Let Delivery Lifecycle own cross-repository mutation authority. Repository Knowledge only routes to that owner. -- Skip an independent preflight challenger for a strict simplification that adds no interface, state, dependency, or broader behavior. -- Reject `remove-repo` in a linked worktree before mutation. -- Keep the existing watcher patch, keyless operation, empty-directory behavior, and Windows launcher repair. -- Use checkpoint native reviews and one final native review. A separate coherency review does not exist. -- Run semantic trace closure only for executable production-code behavior with a real runnable entry point. Written instructions use deterministic checks and native review. - -## Context and Orientation - -`assets/skills/delivery-lifecycle/references/delivery-lifecycle.md` owns delivery authority. `assets/skills/repository-knowledge/SKILL.md` owns RepoWise lookup routing. `assets/skills/design-preflight/SKILL.md` owns the strict-simplification challenge exemption. `assets/runtime/repowise_bootstrap.py` starts RepoWise. `kit.py` installs and diagnoses it. `tests/test_kit.py` verifies behavior and rule ownership. - -Applicable immutable Plan records: - -- `.agent/plan-history/plan-summary.20260822T050100617085Z.fd7dfe4c94e461a1824112794d31e1372d316ccf79eed8a3937d2754c1157e40.md` -- `.agent/plan-history/plan-summary.20260822T065923051937Z.4415ee79c8b0327ba824768113192b4f60662d355fb4931876ec995a214a5526.md` -- `.agent/plan-history/plan-summary.20260823T052048899607Z.c539b46a7e5fa56092a382fef046fd00d4271c42c4fda8e0f0e2216ce94df122.md` -- `.agent/plan-history/plan-summary.20260824T031427928859Z.f30d03e6b396d05f07f5ce7eebc8b8e8b81e2b1cfe8ebc739342a6e444ca6968.md` -- `.agent/plan-history/plan-summary.20260824T135017227348Z.7cfbec79d5ce39f1a1d436a31dccfe0669c616f252b6793d4b90dc2b34ad13d6.md` -- `.agent/plan-history/plan-summary.20260824T164719361941Z.f1479c9effab9071b8ccaa86dce1dbee407b79647c6bb7d542aea8c75caae32b.md` -- `.agent/plan-history/plan-summary.20260825T002758364682Z.4eba52594f2ef5bdbe93f4f0ead7b61802e894668d23c749b5af459f65a19437.md` -- `.agent/plan-history/plan-summary.20260825T002911279202Z.940432714b78524077326cf1dea7571142fa6038e878a2fb7e884024bc8775a8.md` - -The first CPK-046 record is superseded only where it names a final coherency review. The second record replaces that term with the toolkit’s final native review. All other decisions are carried. - -## Product Boundary - -[Delivery Lifecycle](../../assets/skills/delivery-lifecycle/references/delivery-lifecycle.md) limits write authority to the current repository and repositories explicitly named by the user. [Repository Knowledge](../../assets/skills/repository-knowledge/SKILL.md) must report an out-of-scope tooling failure instead of repairing another repository. - -The supported runtime is a normal Git checkout or a normal linked worktree. Bare-backed worktrees retain upstream behavior. The implementation adds no new command, configuration, state marker, wrapper hook, LLM dependency, or primary-checkout resolver. - -## Boundary Inventory - -| Boundary | Condition and contrast | Entry points | Required oracle | Scenario | -| --- | --- | --- | --- | --- | -| B1 | A failure in the current or explicitly named repository permits in-scope work. The same failure in another repository permits read-only diagnosis only. | Delivery Lifecycle and Repository Knowledge failure handling. | The authority rule occurs only in Delivery Lifecycle. Repository Knowledge reports failure and routes to it. | S1 | -| B2 | A correction that rejects a larger design, uses an existing capability, and broadens no behavior skips the challenger. A correction that adds an interface, state, dependency, fallback, or supported behavior keeps the challenger. | Design Preflight correction entry gate. | Both sides remain explicit. Only the strict simplification receives the exception. | S2 | -| B3 | A manifest-owned outdated RepoWise command upgrades. An unowned mismatch stops. | Core installation and runtime discovery on POSIX and Windows. | Only the owned path changes and the final command reports `0.45.0`. | S3 | -| B4 | A normal linked worktree uses its own index and Git's shared hook path. A normal checkout keeps its existing behavior. | Setup, automatic bootstrap, Doctor, watcher, MCP, and post-commit maintenance. | Linked changes reach the linked index without changing the base index. Both repository forms remain ready. | S4 | -| B5 | `remove-repo` in a linked worktree stops before mutation. The same command in a normal checkout removes only managed integration. | POSIX and PowerShell removal launchers through `kit.py`. | Linked configuration, index, and shared hook remain unchanged. Normal removal still succeeds. | S5 | -| B6 | Executable production-code behavior with a real runnable entry point uses trace closure. Written instructions, tests, documentation, and static configuration do not. | Scenario Discrimination before native review. | Instruction-only work uses deterministic checks and native review without a semantic trace loop. Runtime behavior keeps trace closure. | S6 | - -No source clause is deferred or a contract gap. Bare-backed worktrees are opaque upstream behavior and receive no toolkit-specific promise. - -## Scenario Proof - -| Scenario | Discriminator | Minimal contrast | Production path and terminal oracle | Runnable check | -| --- | --- | --- | --- | --- | -| S1 | Repository write authority | Same tooling failure inside task scope and in an unnamed repository | Failure to Delivery Lifecycle authority; only the in-scope repository can change | `test_tool_failure_does_not_expand_repository_write_scope` | -| S2 | Correction shape | Strict deletion/upstream reuse and a correction that adds one listed moving part | Design Preflight entry gate; only the strict simplification skips the challenger | `test_strict_simplifications_skip_the_preflight_challenger` | -| S3 | Manifest ownership | Outdated command at the recorded fixed path and the same version elsewhere | `ensure_repowise`; owned command upgrades and unowned command raises conflict | Focused owned-upgrade and unowned-mismatch runtime tests | -| S4 | Repository form | Normal checkout and linked worktree from the same base | Launcher to RepoWise hook, watcher, MCP, and separate index state | Real linked-worktree setup, Doctor, watcher, MCP, and commit smoke tests | -| S5 | Removal repository form | Normal checkout and linked worktree | `remove_repo`; linked form stops before the first mutation and normal form completes | Focused removal tests with configuration, index, and hook oracles | -| S6 | Review source type | Executable production behavior and written instruction behavior | Scenario Discrimination gate; only the executable side invokes semantic trace closure | `test_boundary_trace_closure_blocks_native_review` | - -## Plan of Work - -### CP1 — Containment and authority - -Add one cross-repository write-authority guard to Delivery Lifecycle. Route Repository Knowledge failures to it. Add the strict-simplification challenge exception to Design Preflight. Limit semantic trace closure to executable production-code behavior. Verify that each rule has one owner, update the focused tests and documentation, run one checkpoint native review, and commit the accepted checkpoint. - -### CP2 — Minimal RepoWise correction - -Pin RepoWise `0.45.0`. Upgrade only the manifest-recorded toolkit-owned executable. Resolve hooks with `git rev-parse --git-path hooks`. Reject linked-worktree removal before mutation. Preserve existing runtime behavior, update the authoritative documentation and dependency records, and regenerate the manifest. Run one checkpoint native review and commit the accepted checkpoint. Then run one final native review of the complete candidate. - -## Validation - -- Prove one-owner routing for cross-repository authority and strict-simplification challenge behavior. -- Prove owned upgrades, matching-version reuse, unowned conflicts, Windows repair, and empty-directory behavior. -- Exercise setup, bootstrap, Doctor, watcher indexing, hook commits, and MCP startup in real normal and linked worktrees. -- Confirm that a linked worktree has its own index and does not modify the base index. -- Confirm that linked removal stops before configuration, index, or hook mutation. -- Run the complete Python suite, compilation checks, shell and PowerShell checks, rule-owner checks, and checksum validation. -- Install the reviewed candidate and repeat Doctor plus linked-worktree MCP smoke tests before review closure. - -## Outcomes & Retrospective - -RepoWise uses its upstream linked-worktree model. A tooling failure cannot silently authorize edits in another repository. The toolkit has one native review sequence and no separate coherency review. diff --git a/docs/plans/cpk-047-bounded-preflight-publication.md b/docs/plans/cpk-047-bounded-preflight-publication.md deleted file mode 100644 index 786c5a6..0000000 --- a/docs/plans/cpk-047-bounded-preflight-publication.md +++ /dev/null @@ -1,75 +0,0 @@ -# Repair worktree handoffs, preflight, and publication - -This ExecPlan is the durable CPK-047 implementation specification. Maintain it according to `.agent/PLANS.md`. - -## Purpose - -Plan History can leave an applicable untracked record in the worktree that accepted a Plan after implementation moves to another worktree. That redundant file can later block a fast-forward of local `main`. - -Design Preflight can give its challenger a source surface that is broader than the accepted task. Publication can also confuse local native review with GitHub PR review or finish while local `main` remains stale. - -Release these corrections as version `0.23.2` on branch `cpk-047-bounded-preflight-publication` from commit `94a23813a5337b1716cc43de69b8571bec24c2aa`. - -## Product boundary - -[Plan History](../../assets/skills/plan-history/SKILL.md) owns applicable record discovery, immutable content, and cross-worktree handoff. [Coordination](../../assets/skills/delivery-lifecycle/references/coordination.md) owns delegated-task liveness. [Design Preflight](../../assets/skills/design-preflight/SKILL.md) owns challenger scope and its two phases. [Publication](../../assets/skills/publication/references/publication.md) owns PR sequencing and integration completion. - -Adversarial Review retains local review and finding authority. Supported Model retains one-attempt error handling. Git Isolation retains task-start divergence rules. The task adds no hook behavior, helper, parser, daemon, database, dependency, or runtime state machine. - -## Decisions - -- Relocate an applicable untracked Plan record by copying it to the task worktree, comparing bytes, and removing only the redundant source copy. -- Keep central and specification-sibling records in the task worktree because they have different discovery roles. -- Bound preflight by the accepted outcome. Permit source expansion only through authoritative product evidence or a direct composing relationship. -- Keep one challenger identity for both phases. Elapsed time does not authorize a duplicate task. -- Treat local native review and GitHub PR review as separate cumulative gates. -- After a remote squash merge, fast-forward local `main` to `origin/main` before publication completes. -- Preserve unrelated untracked files. Stop only for tracked changes, divergence, or an actual overwrite conflict. - -## Checkpoints - -### CP1 — Transfer pending Plan History - -Update the Plan History owner and its deterministic owner test. Require discovery across worktrees in the same Git repository. Copy applicable untracked records to the same task-worktree path. Remove a source copy only after exact byte equality. Retain unique, tracked, unrelated, or different-content records. - -Run the focused Plan History checks, one checkpoint native review, and one local checkpoint commit. - -### CP2 — Bound preflight - -Add a task-bound source packet and an evidence-backed `source_scope` result. Keep one challenger for both phases. Route generic liveness to Coordination and one-attempt errors to Supported Model. - -Run the focused preflight checks, one checkpoint native review, and one local checkpoint commit. - -### CP3 — Reconcile publication - -Require Plan History handoff before publication classifies worktree state. Require exact local, remote-branch, and PR-head identity. Keep local and GitHub review gates separate. After squash merge, fetch `origin`, fast-forward the clean local-main worktree, prove integration, and monitor post-merge CI. - -Run the focused publication checks, one checkpoint native review, and one local checkpoint commit. Then run one final native review of the complete candidate. - -## Validation - -- Prove safe Plan record relocation, collision retention, tracked-record protection, and repeatable partial-copy handling. -- Prove bounded preflight sources, supported expansion, one live challenger, and no automatic restart. -- Prove separate review gates, exact current-head review, local-main fast-forward, and safe stops. -- Run the complete Python suite, skill validation, link checks, shell and PowerShell checks, manifest validation, and `git diff --check`. -- Install the final reviewed candidate and require Doctor to report `Result: ready`. - -## Prior Plan reconciliation - -Record: `.agent/plan-history/plan-summary.20260825T172626414955Z.9eaf7888a286b18f69d5a94869ee99522214d23dd715a553664a2041108fced3.md` - -Status: superseded - -Reason: The publication checkpoint did not first relocate pending Plan History records from the `main` worktree. - -Replacement: Add CP1 relocation before preflight and publication. Apply that owner before publication classifies worktree state. - -Scope: unfinished subtasks CP1 and CP2. - -Record: `.agent/plan-history/plan-summary.20260825T173129857080Z.a3ee26a1802fb85c5a0a100ccb3c33c1a6fff358bd20b65636adc61f8d0de377.md` - -Status: carried - -Reason: This record is the accepted CPK-047 implementation contract. - -The completed CPK-035, CPK-042, CPK-043, CPK-044, and final CPK-046 decisions remain carried. diff --git a/docs/plans/cpk-048-shared-instruction-reconciliation.md b/docs/plans/cpk-048-shared-instruction-reconciliation.md deleted file mode 100644 index 0341d8f..0000000 --- a/docs/plans/cpk-048-shared-instruction-reconciliation.md +++ /dev/null @@ -1,105 +0,0 @@ -# Reconcile shared agent and Plan instructions - -This ExecPlan is the durable CPK-048 implementation specification. Maintain it according to `.agent/PLANS.md`. - -## Purpose - -The toolkit installs global agent and ExecPlan instructions. Repository files can override those instructions, but the installer does not update repository-owned files. - -Older repositories contain copied Plan contracts and generic lifecycle rules. Those copies can hide current checkpoint guidance or conflict with maintained skills. - -Correct the documentation and the eligible projects before publication of version `0.23.2`. - -## Product boundary - -[ExecPlan rules](../../.agent/PLANS.md) remain the only shared Plan contract. [Rule ownership](../../assets/skills/toolkit-maintainer/SKILL.md) prevents duplicate toolkit owners. [Git isolation](../../assets/skills/delivery-lifecycle/references/git-isolation.md) protects user work during the project audit. - -The task adds no migrator, Doctor check, skill, runtime behavior, dependency, or version change. Repository-specific product, build, security, and release rules remain in their nearest `AGENTS.md` file. - -## Decisions - -- Document the global instruction scope and repository override priority in the README. -- Remove generic repository Plan copies instead of maintaining duplicate contracts. -- Preserve Meridian's production-complete checkpoint rule in its root `AGENTS.md`. -- Remove only generic toolkit lifecycle rules from project `AGENTS.md` files. -- Archive untracked and non-Git Plan copies before removal. -- Ignore the five dirty Meridian worktrees that the user identified as historical artifacts. -- Leave `billing-reconciler` unchanged because the user has active work on another device. -- Keep FacetOS's local Plan contract until its active Task 002.04 has a separate migration. -- Create local documentation commits in eligible Git repositories. Do not push them. -- Keep toolkit version `0.23.2` because its tag has not reached GitHub. - -## Checkpoints - -### CP1 — Document shared instruction precedence - -Update the README. Explain the global files, repository override priority, manual maintenance boundary, and safe removal of generic copies. - -Run documentation checks and one checkpoint native review. Create one local toolkit checkpoint commit. - -### CP2 — Reconcile eligible projects - -Work from `/home/mbeutler/Projects`. Inventory Plan copies with: - - find /home/mbeutler/Projects -path '*/.agent/PLANS.md' -type f -print | sort - -Before edits, this command must show the toolkit file and 25 copies. Exclude these five dirty Meridian worktrees: - -- `meridian-task-063e` -- `meridian-task-063e-rebuild` -- `meridian-task-063f` -- `meridian-task-063f-rebuild` -- `meridian-task-084a2` - -The user later excluded `billing-reconciler`. FacetOS also remains excluded because its active plan uses the local contract. Migrating that active plan is separate work. - -Refresh each distinct Git remote once with `git fetch --prune`. Operate only when `git status --short` shows no unexpected tracked change. Fast-forward a clean selected base branch with `git merge --ff-only @{upstream}`. Then require `git merge-base --is-ancestor @{upstream} HEAD` to succeed. Use the `cpk-048-instruction-reconciliation` branch in independent repositories. Use the existing branch in each eligible Meridian worktree. - -Archive each untracked or non-Git Plan copy under `/home/mbeutler/.local/share/codex-practical-kit/audits/cpk-048/`. Preserve its path relative to `/home/mbeutler/Projects`. Record its SHA-256 value before removal. Run `sha256sum` on the source and archive. Both values must match. - -Remove 18 eligible generic Plan copies. Move real project rules to the nearest `AGENTS.md`, then remove stale generic lifecycle text. Update current workflow documents that route agents to the removed copy. Do not rewrite completed plans. Run the inventory command again. It must show the toolkit file and seven excluded project files. - -In each Git candidate, stage only the removed Plan, focused `AGENTS.md` rules, and current workflow documents that route to the removed Plan. Run `git diff --cached --check`; it must produce no output. Create a synthetic commit from the staged tree, then run `codex review --commit `. If the review has no applicable finding, create one local documentation commit. Preserve unrelated untracked files. Do not push external repositories. - -From `/home/mbeutler/Projects/codex-practical-kit`, run: - - ./run-tests.sh - sh -n doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh - git diff --check - sha256sum --check MANIFEST.sha256 - -The test command must report success. The other commands must produce no error. Run one final native review of the complete toolkit candidate. Apply review closure, run `./install.sh`, then run `./doctor.sh`. Doctor must report `Result: ready`. Continue toolkit publication only after these results. - -## Validation - -- Confirm that the toolkit still has one canonical `.agent/PLANS.md`. -- Confirm that 18 eligible copied Plan files are removed. Confirm that Billing, FacetOS, and five dirty Meridian worktrees remain unchanged. -- Confirm that archived files have matching SHA-256 values. -- Confirm that eligible `AGENTS.md` files contain no stale local Plan route or copied toolkit lifecycle rule. -- Confirm that external commits change only focused instructions and current workflow documents. -- Run the complete toolkit test, syntax, link, manifest, and diff checks. -- Install the reviewed toolkit and require Doctor to report `Result: ready`. - -## Prior Plan reconciliation - -Record: `.agent/plan-history/plan-summary.20260823T052048899607Z.c539b46a7e5fa56092a382fef046fd00d4271c42c4fda8e0f0e2216ce94df122.md` - -Status: carried - -Reason: CPK-042 remains authoritative for semantic checkpoints and final native review. - -Record: `.agent/plan-history/plan-summary.20260825T173129857080Z.a3ee26a1802fb85c5a0a100ccb3c33c1a6fff358bd20b65636adc61f8d0de377.md` - -Status: carried - -Reason: The final CPK-047 publication and integration rules remain authoritative. - -Record: `.agent/plan-history/plan-summary.20260825T183857932150Z.47ec1ac118b8c6c23f961b4099708aacc7031581a744bc389e6795e1c2007796.md` - -Status: superseded - -Reason: The user excluded Billing. FacetOS's active plan requires a separate migration. - -Replacement: CP2 removes 18 copies and preserves Billing and FacetOS. - -Scope: unfinished subtasks CP2 diff --git a/docs/plans/cpk-050-repowise-partial-init.md b/docs/plans/cpk-050-repowise-partial-init.md deleted file mode 100644 index 714ce66..0000000 --- a/docs/plans/cpk-050-repowise-partial-init.md +++ /dev/null @@ -1,137 +0,0 @@ -# Recover Incomplete RepoWise Initialization - -This ExecPlan is a living specification until review closure. Maintain it according to `.agent/PLANS.md`. - -## Purpose / Big Picture - -Codex must start with the required RepoWise graph after a normal RepoWise upgrade. An older RepoWise version can leave a populated index without a completed sync commit. The current bootstrap mistakes this state for a complete index. Its update fails, and required MCP startup terminates Codex. - -After this change, the bootstrap rebuilds that incomplete index once. It then runs the normal catch-up update and starts RepoWise MCP. - -Work occurs on branch `fix/cpk-050-repowise-partial-init`. The base branch is `main` at `b4c592c92e15a42c0a82b8dfd4a793ac0f81f2da`. One task branch isolates the writable implementation stream. - -Release this bugfix as version `0.23.4`. - -## Surprises & Discoveries - -- RepoWise 0.41.0 wrote the reported index. The database contains 126 pages, but `last_sync_commit` is null. -- RepoWise 0.45.0 reports that database as healthy. Its incremental update still stops with `No previous sync found`. -- RepoWise 0.45.0 ordinary no-prose initialization repaired a disposable copy in 48.4 seconds. -- The repaired copy required one normal update to refresh the stored indexed revision. -- A null sync commit is valid before the first Git commit. Recovery must also require an existing `HEAD`. - -## Decision Log - -- Read the RepoWise sync marker from `state.json`. Do not inspect or change `wiki.db`. -- Treat an existing index as incomplete only when `HEAD` exists and `last_sync_commit` is not a nonempty string. -- Reuse the existing noninteractive `INIT_ARGS`. Do not add `--force` or a second recovery command. -- If an index directory existed before recovery, run the normal catch-up update after initialization. -- Keep RepoWise 0.45.0. RepoWise 0.46.0 has no release note for this startup state. -- Keep RepoWise required. Do not let Codex continue without the code graph. -- Increment the committed source version from `0.23.3` to `0.23.4` for this bugfix. - -## Outcomes & Retrospective - -The bootstrap now repairs an incomplete index from an older RepoWise version. It preserves normal startup before the first Git commit. - -Directory presence was not a sufficient readiness signal. The completed sync commit identifies the state that RepoWise can update. - -## Context and Orientation - -`assets/runtime/repowise_bootstrap.py` owns automatic RepoWise startup. Its `bootstrap()` function selects the Git root and prepares the index. It then installs the Git hook, starts the watcher, and starts RepoWise MCP. - -`tests/test_kit.py` contains the direct bootstrap checks. `docs/REPOWISE.md` defines the user-visible runtime behavior. `docs/roadmap.md` is the only lifecycle-state record. - -The existing code uses the `.repowise` directory as its only initialization signal. The RepoWise CLI uses `.repowise/state.json` and requires `last_sync_commit` for normal incremental updates. - -## Product Boundary - -[Scope boundaries](../../assets/skills/design-preflight/references/scope-boundaries.md) limit this task to automatic bootstrap behavior. - -The installed Python bootstrap is `composes`. RepoWise CLI behavior, Git, the Codex required-MCP setting, and the installer are `opaque`. Repository commands, agent routing, removal, and the RepoWise database format are also `opaque`. - -The current production use cases include normal checkouts, linked worktrees, and empty project folders. This task preserves these use cases. It adds the reported normal upgrade state to bootstrap preparation. - -The supported model has one user, one Codex writer, a normal local filesystem, and normal Git. The observed trigger needs no fault injection. The toolkit controls its RepoWise version and bootstrap gate. - -This task adds no database inspection, direct state change, index removal, backup, retry loop, dependency, optional MCP path, or generic fallback. It does not add recovery for malformed JSON, I/O errors, permission errors, interruption, or outside changes. - -## Boundary Inventory - -[Scenario discrimination](../../assets/skills/design-preflight/references/scenario-discrimination.md) owns this inventory. [Owner composition](../../assets/skills/design-preflight/references/owner-composition.md) owns the startup sequence. - -| Boundary | Condition and contrast | Entry point | Required oracle | Scenario | -| --- | --- | --- | --- | --- | -| B1 | A rooted bootstrap reaches usable RepoWise MCP. Startup termination or an unavailable graph is the contrast. | `main()` to `bootstrap()` | MCP receives the Git root and returns its status. | S1 | -| B2 | Only an empty non-Git directory receives `git init`. One ordinary file is the contrast. | `bootstrap()` non-Git gate | Only the empty directory enters rooted setup. | Existing checks | -| B3 | With `HEAD`, an absent index or an index without a nonempty sync commit needs initialization. A nonempty commit string is complete. | `bootstrap()` index gate | The incomplete side initializes. The complete side does not. | S1 | -| B4 | An index directory that existed before startup receives catch-up when `HEAD` exists. No `HEAD` is the contrast. | `bootstrap()` catch-up gate | Recovery and normal existing indexes update. A new first index does not. | S1, S2 | -| B5 | A linked worktree keeps its root and index. Redirection to the primary checkout is the contrast. | `git_root()` and `bootstrap()` | All rooted commands use the linked path. | Existing check | -| B6 | A ready watcher permits MCP. An exited watcher prevents MCP. | `bootstrap()` readiness gate | MCP starts only after readiness, and cleanup stops the watcher. | Existing checks | -| B7 | POSIX stops one watcher. Windows stops the watcher process tree. | `stop_watcher()` | The applicable process owner stops and waits. | Existing checks | -| B8 | Setup diagnostics use stderr. MCP keeps stdout for the protocol. | `run_setup()` and MCP call | Setup output cannot enter the protocol stream. | Existing check | - -Every source clause in the accepted task boundary has a disposition. B3 changes because directory presence cannot prove a completed RepoWise initialization. No accepted clause remains a contract gap. - -## Scenario Proof - -| Scenario | Discriminator | Minimal contrast | Production path and terminal oracle | Runnable check | -| --- | --- | --- | --- | --- | -| S1 | `last_sync_commit` with an existing `HEAD` | Null and nonempty string in otherwise equal state files | Bootstrap readiness gate to init or no init, hook, catch-up, ready watcher, rooted MCP, and cleanup | `test_bootstrap_recovers_index_without_sync_commit` and `test_bootstrap_initializes_once_and_always_installs_hook` | -| S2 | `HEAD` with an existing index and null sync commit | No commit and one commit | Bootstrap readiness gate to no recovery or recovery, then hook, watcher, MCP, and cleanup | `test_bootstrap_does_not_reinitialize_before_first_commit` | - -For S1, the incomplete side must run the exact `INIT_ARGS` once. It must then run one catch-up update because the index directory existed before startup. The complete side must skip initialization and run one update. - -For S2, the no-commit side must skip initialization and update. It must still install the hook and reach watcher, rooted MCP, and cleanup. - -The input-domain and path-transition lenses apply. Collection semantics do not apply because the bootstrap selects one repository state. - -## Plan of Work - -Add one small JSON reader to `assets/runtime/repowise_bootstrap.py`. The reader returns true only for a nonempty string in `last_sync_commit`. - -In `bootstrap()`, retain the original index-directory state and resolve `HEAD` once. Initialize when the directory is absent. Also initialize when the directory exists, `HEAD` exists, and the sync marker is incomplete. - -After setup, install the hook as before. If the index directory existed and `HEAD` exists, run the existing update command. Keep the watcher and MCP lifecycle unchanged. - -Update the focused tests in `tests/test_kit.py`. Update `docs/REPOWISE.md` with the completed-index rule. - -## Concrete Steps - -Work from `C:\Users\mikeb\Projects\codex-practical-kit`. - -1. Change the bootstrap readiness gate and its focused checks. -2. Run the named Scenario Proof checks. -3. Run the complete Python suite and repository checks. -4. Update only documentation that became incorrect. -5. Run trace closure and native adversarial review before review closure. - -## Validation and Acceptance - -The S1 checks must prove both marker values and the complete production sequence. The null side must initialize and update. The nonempty side must update without initialization. - -The S2 check must prove that a null marker does not cause repeated initialization before the first commit. - -Run `python -m unittest tests.test_kit.RepoWiseRuntimeTests`. Then run `python -m unittest` for the complete suite. Record baseline errors separately if they remain outside this task. - -Run the repository checksum, compilation, shell, PowerShell, and rule-owner checks through the existing repository test commands. - -## Idempotence and Recovery - -Normal startup is idempotent after RepoWise writes a completed sync commit. The bootstrap makes one initialization attempt. If that command fails, startup stops with the command status. - -The implementation does not change the reported repository. A disposable copy proves the external RepoWise behavior. - -## Artifacts and Notes - -Keep detailed command results in `.agent/test-results/cpk-050-repowise-partial-init.md`. Do not stage that file. - -The disposable proof repository is outside this repository. It contains a copied RepoWise index and no authoritative user data. - -## Interfaces and Dependencies - -Use only Python `json`, `subprocess`, and `pathlib`. Do not add a package. - -Keep `bootstrap(repowise: str, cwd: Path) -> int` and `main(argv: list[str] | None = None) -> int` unchanged. Add one private readiness predicate with a `Path` input and a Boolean result. - -Final note: this plan replaces directory-only initialization detection because that test cannot identify the reported incomplete index. diff --git a/docs/plans/cpk-052-review-trace-closure.md b/docs/plans/cpk-052-review-trace-closure.md deleted file mode 100644 index 2113cc4..0000000 --- a/docs/plans/cpk-052-review-trace-closure.md +++ /dev/null @@ -1,133 +0,0 @@ -# Restore Independent Trace Coverage and Severity-Based Review Stops - -This ExecPlan is a living specification until review closure. Maintain it according to `.agent/PLANS.md`. - -## Purpose / Big Picture - -Review repetition must not turn an ordinary defect into a severe defect. A validated P2 finding must use the correction-authority gate on every pass. Only validated severe impact plus a correction that is not a direct repair can start Defect Diagnostic. - -Trace closure must also inspect test coverage independently. For each eligible native review, one fresh read-only subagent receives the accepted boundaries, the production paths, and the named tests. It reports missing tests before native review starts. The coordinator cannot attest its own trace. - -Work occurs on branch `fix/cpk-052-review-trace-closure`. The base branch is `main` at `56404d5a470e2c4214b42377f2e3aa31d3fafb14`. Release this bugfix as version `0.23.6`. - -## Surprises & Discoveries - -- The severity rule still contained the old third-counted-pass stop after the direct-repair gate was added. -- The current trace owner requires evidence inspection but does not identify an independent executor. -- The old forward fixture still requires trace closure to derive requirements again. This conflicts with the current accepted-inventory rule. -- A reuse-only final closure can bypass a fresh verifier unless the rule covers every closure invocation. - -## Decision Log - -- Remove only the consecutive production-defect counter and its severe-stop status. Preserve normal review-pass numbers. -- Keep correction-authority and contract-gap stops unchanged. -- Use one fresh read-only subagent with no inherited task conversation for every eligible trace closure. This includes reuse-only closure. -- Give the subagent the canonical Scenario Discrimination, Owner Composition, and Full-set Results rules. -- Give the subagent the accepted boundary inventory and Scenario Proof, exact review boundary, current diff and production sources, named test bodies and results, and reusable rows or an explicit empty set. -- Keep trace closure limited to executable production behavior with a real runnable entry point. -- Keep native review independent. The trace subagent does not edit, delegate, start another trace, run Design Preflight, or start native review. -- Do not add a new skill, hook, parser, dependency, state machine, coverage percentage, or mutation framework. -- Increment the committed source version from `0.23.5` to `0.23.6`. - -## Plan History Reconciliation - -CPK-044 is superseded only where it preserves the old three-pass breaker as an opaque owner. This task makes validated severe impact and the direct-repair gate the only severe-stop selector. - -CPK-045 is superseded only where its trace fixture requires independent requirement derivation before it accepts the boundary inventory. This task restores its fresh read-only verifier but gives that verifier the accepted inventory as the only semantic input. - -CPK-046 remains authoritative. Semantic trace closure still applies only to executable production behavior with a real runnable entry point. Written instructions use deterministic checks and native review. - -## Context and Orientation - -`assets/skills/adversarial-review/SKILL.md` owns finding validation, correction authority, and severe-stop selection. - -`assets/skills/design-preflight/references/scenario-discrimination.md` owns trace eligibility, evidence, execution identity, review scope, reuse, and native-review independence. `preflight-review.md` owns the structured result interface. - -`tests/fixtures/cpk045-boundary-forward.md` is a direct deterministic fixture for the trace rule. `tests/test_kit.py` contains the focused rule-owner checks. `docs/roadmap.md` is the only tracked lifecycle-state record. - -## Product Boundary - -The normal use cases are local full, checkpoint, delta, and final native reviews. Findings can come from local review, PR review, CI, audit, or a user. Every finding source uses the same validation and correction-authority gate. - -The supported model has one coordinator and one writer. A fresh trace subagent is read-only. Concurrent mutation, retry after tool failure, and hostile evidence are outside the supported model. - -The change does not modify Defect Diagnostic, native discovery, review lenses, publication, runtime product code, or completed historical plans. - -## Boundary Inventory - -| Boundary | Condition and contrast | Entry point | Required oracle | Scenario | -| --- | --- | --- | --- | --- | -| B1 | Review-pass ordinal does not escalate P2. The old contrast escalates the third P2 pass. | Finding validation to correction authority | Repeated P2 stops for correction authority and does not start Defect Diagnostic. | S1 | -| B2 | Validated P0/P1 or equivalent severe impact and a non-direct correction selects the severe path. P2, raw severity, or a direct repair does not. | Severity validation to severe breaker | Only the validated severe, non-direct side starts Defect Diagnostic. | S2, S3 | -| B3 | A nonsevere non-direct correction and an undefined result keep separate stop owners. | Accepted-result and correction-authority gates | The status names correction authority or contract decision. | S4 | -| B4 | One fresh clean-context read-only subagent executes each eligible closure. Coordinator or reused-context attestation is invalid. | Trace eligibility to closure result | The result identifies the fresh executor. | S5 | -| B5 | The verifier receives every canonical rule and evidence input and reports missing tests. An incomplete packet or weak test evidence fails. | Trace packet to evidence inspection | `missing_tests` is explicit, and any missing obligation blocks native review. | S6, S7 | -| B6 | Closure scope matches the selected review boundary. Only unchanged rows closed by a fresh verifier can be reused. | Review-mode selection to closure composition | A fresh verifier handles new, invalidated, and reuse-only closure. | S8, S9 | -| B7 | Only executable production behavior uses semantic trace closure. Native review receives no trace result, and neither stage recurses. | Eligibility gate to native discovery | Written rules use deterministic checks. Eligible code is closure-gated. | S10, S11 | - -Every authoritative source clause has a disposition in the accepted preflight result. No contract gap remains. - -## Scenario Proof - -| Scenario | Discriminator and contrast | Terminal oracle | Runnable check | -| --- | --- | --- | --- | -| S1 | First and repeated P2 pass with all other facts equal | Both use ordinary correction authority. | `test_review_stop_diagnostics_are_per_finding_and_mandatory` | -| S2 | Validated P1 and P2 with the same non-direct correction | Only P1 can start Defect Diagnostic. | Same focused stop check | -| S3 | Direct and non-direct repair for the same validated severe defect | Direct repair proceeds; non-direct repair stops severely. | Same focused stop check | -| S4 | Defined wrong result and undefined result | Correction-authority and contract-gap statuses remain distinct. | Same focused stop check | -| S5 | Fresh no-history verifier and coordinator self-attestation | Only the fresh verifier can close the trace. | `test_boundary_trace_closure_blocks_native_review` | -| S6 | Complete packet and each required input omitted | Only the complete packet can pass. | Same focused trace check | -| S7 | Paired terminal proof and missing or weak test evidence | Missing tests are named and block review. | Same focused trace check | -| S8 | Unchanged verified row and changed or coordinator-authored row | Only the unchanged verified row is reusable. | Same focused trace check | -| S9 | Full, checkpoint, delta, final, and reuse-only closure | Each mode closes its exact boundary through a fresh verifier. | Same focused trace check | -| S10 | Executable production behavior and written instruction behavior | Only executable behavior uses semantic trace closure. | Same focused trace check | -| S11 | Native input without and with trace conclusions | Only independent native input is valid; no stage recurses. | Same focused trace check and `test_native_review_does_not_recurse` | - -The input-domain, path-transition, and collection-semantic lenses all apply. - -## Plan of Work - -Change the severe breaker in its existing owner. Delete the obsolete consecutive-defect count and its dedicated status. Keep validated severity, direct repair, correction authority, contract gaps, and normal pass numbers. - -Change the trace owner and structured result. Require one fresh clean-context verifier for every eligible invocation. Name the canonical rules and evidence packet. Add executor identity and `missing_tests` to the result. Update the existing forward fixture so it tests accepted-inventory evidence closure instead of requirement re-derivation. - -Update the two focused checks, the version, roadmap, and manifest. No other owner is needed. - -## Concrete Steps - -Work from `/home/mbeutler/Projects/codex-practical-kit`. - -1. Update the canonical severe-stop and trace-closure owners. -2. Update the direct fixture and focused tests. -3. Run the focused tests and complete repository checks. -4. Regenerate the manifest after source and documentation are final. -5. Run native adversarial review before review closure. - -## Validation and Acceptance - -Run: - - python3 -m unittest tests.test_kit.IntegrationTests.test_boundary_trace_closure_blocks_native_review - python3 -m unittest tests.test_kit.IntegrationTests.test_native_review_does_not_recurse - python3 -m unittest tests.test_kit.IntegrationTests.test_review_stop_diagnostics_are_per_finding_and_mandatory - python3 -m unittest tests.test_kit.IntegrationTests.test_lifecycle_skills_and_version - ./run-tests.sh - sh -n doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh - git diff --check - sha256sum --check MANIFEST.sha256 - -The focused checks must prove the B1 through B7 contrasts. The complete checks must find no rule-owner, package, or platform regression. - -## Idempotence and Recovery - -The change is declarative and idempotent. If a check or review fails, stop and report it. Do not retry by replacing a healthy verifier or reviewer. - -## Artifacts and Notes - -Keep detailed command and review results in `.agent/test-results/cpk-052-review-trace-closure.md`. Do not stage that file. - -## Interfaces and Dependencies - -No executable interface or dependency changes. The existing review and Design Preflight skills remain the public instruction routes. - -Final note: one independent evidence pass catches missing tests without turning trace closure into a second requirements review. diff --git a/docs/plans/cpk-053-continuous-path-proof.md b/docs/plans/cpk-053-continuous-path-proof.md deleted file mode 100644 index f5ca71c..0000000 --- a/docs/plans/cpk-053-continuous-path-proof.md +++ /dev/null @@ -1,128 +0,0 @@ -# Require Continuous Production-Path Proof - -This ExecPlan is the stable implementation specification for CPK-053. Maintain it according to `.agent/PLANS.md`. - -## Purpose - -Trace closure records entry points, gates, owners, checks, and terminal results as separate facts. A verifier can combine component evidence even when no check traverses the complete production path. - -After this change, one named runnable check must prove each accepted production path. The check must invoke the real repository entry point. Each proof case must follow one causal path through every in-scope production hop to the terminal oracle. - -This bugfix uses version `0.23.7`. Work occurs on branch `fix/cpk-053-continuous-path-proof` from `main` at `ee3aa1464e4adebdff43ff8bee3a01c52d6c9221`. The isolation form is one task branch. - -## Applicable Plan History - -- `.agent/plan-history/plan-summary.20260901T024803899174Z.f5becdd56d889aba50bf375a29ab0feb9012128e404e73e7a664e0243eb5ab8f.md` - -The central record links this specification to the accepted Plan. - -## Decision Log - -- Decision: Keep Owner Composition as the only owner of causal path and seam rules. - Rationale: One shared owner prevents rule drift and covers each trace consumer. -- Decision: Add one ordered `production_hops` list instead of required and observed lists. - Rationale: The exact named check supplies the observation evidence. A second list would duplicate the path inventory. -- Decision: Permit deterministic callbacks and async continuations that the check drives. - Rationale: Causal traversal does not require one synchronous call stack. -- Decision: Exclude concurrent thread ordering unless an accepted product requirement includes it. - Rationale: The supported model does not include nondeterministic ordering by default. -- Decision: Use deterministic checks and native review for this task. - Rationale: This task changes static toolkit rules, not executable production behavior. - -## Product Boundary - -[Scope Boundaries](../../assets/skills/design-preflight/references/scope-boundaries.md) limits this task to production-path proof. - -[Owner Composition](../../assets/skills/design-preflight/references/owner-composition.md) owns causal production-path composition and seam placement. [Scenario Discrimination](../../assets/skills/design-preflight/references/scenario-discrimination.md) owns trace evidence and eligibility. The trace result defines the structured interface. Design Preflight uses these owners for initial work and accepted corrections. - -External systems, trace-executor lifecycle, native review, Full-set Results, and publication are opaque. No deferred owner is promoted. - -The scope ceiling excludes live-service requirements, broad UI automation, parsers, runtime instrumentation, coverage thresholds, mutation systems, dependencies, new skills, duplicate rule owners, and exhaustive combinations. - -## Required Outcome - -For each eligible boundary and production entry path, one exact named check must do these actions: - -1. Invoke the real in-repository production entry point. -2. Follow one causal execution through every in-scope production hop. -3. Reach and observe the terminal oracle. - -Separate component checks cannot satisfy this outcome. Disconnected component calls inside one check also cannot satisfy it. - -A deterministic callback or async continuation can be part of the causal execution when the check directly drives it. Concurrent thread ordering stays outside the supported model unless a product requirement includes it. - -A fake, stub, or seam can replace only an opaque external system. Examples include a network, clock, operating system, or third-party provider. A seam that replaces an in-scope production hop leaves the path unclosed. Live external infrastructure is not required. - -## Boundary Inventory - -| Boundary | Condition or invariant | Contrast and oracle | Entry points | Scenario rows | -| --- | --- | --- | --- | --- | -| B1 | One exact check traverses the real entry, every in-scope hop, and the terminal oracle. | A causal path passes. Separate checks, disconnected calls, a skipped hop, or an early stop fail. | Initial preflight, correction preflight, and each trace-closure mode. | S1, S2, S3, S10 | -| B2 | A seam can replace only an opaque external system. | An external-provider fake passes. An in-scope writer or loader fake fails. | Each accepted production entry path. | S4 | -| B3 | A deterministic external fake is sufficient. | The fake can pass without live infrastructure. | A production path with an external dependency. | S5 | -| B4 | Semantic trace closure applies only to executable production behavior with a real entry point. | Eligible production code receives closure. Written artifacts and no-entry units do not. | Trace eligibility and the review gate. | S6, S7 | -| B5 | Every eligible closure uses the existing fresh no-history executor. | Fresh execution passes. Coordinator or reused-context attestation fails. | Full, checkpoint, delta, final, and reuse-only closure. | S8 | -| B6 | Native review stays independent from trace conclusions. | Unprimed native input passes. Trace-primed input fails. | Native discovery. | S9 | - -The user requirement, accepted Plan, and inherited CPK-022, CPK-023, CPK-034, CPK-045, CPK-046, and CPK-052 decisions supply these boundaries. CPK-052 remains authoritative where it supersedes the earlier independent boundary derivation from CPK-045. - -## Scenario Proof - -| Scenario | Discriminator and contrast | Production path | Required oracle | Runnable check | -| --- | --- | --- | --- | --- | -| S1 | Separate entry, intermediate, and terminal checks versus one causal check. | Initial preflight to Owner Composition to Scenario Proof. | Only the causal check is accepted. | `test_scenario_proof_maps_transition_closed_checks` and the forward fixture. | -| S2 | Initial preflight versus accepted-correction preflight. | Both preflight entry routes to Scenario Proof. | Both routes require the same proof. | `test_scenario_proof_maps_transition_closed_checks` and the forward fixture. | -| S3 | Combined component evidence versus one exact production-path check. | Each trace mode to the fresh executor to the native-review gate. | Combined evidence enters `missing_tests` and blocks review. | `test_boundary_trace_closure_blocks_native_review` and the forward fixture. | -| S4 | External-provider fake versus an in-scope owner fake. | Real entry to all in-scope hops to the external boundary and terminal owner. | Only the external fake can close the row. | `test_boundary_trace_closure_blocks_native_review` and the forward fixture. | -| S5 | Deterministic external fake versus a live-service requirement. | Real repository path to the external boundary. | The deterministic fake can pass. | `test_boundary_trace_closure_blocks_native_review`. | -| S6 | Executable production code versus a static toolkit rule. | Trace eligibility to the selected validation path. | Only eligible production code receives semantic closure. | Existing eligibility assertions. | -| S7 | Executable behavior with a real entry versus a unit without one. | Trace eligibility gate. | The no-entry unit receives no invented trace proof. | Existing eligibility assertions. | -| S8 | Fresh no-history executor versus coordinator or reused-context attestation. | Trace invocation to structured result. | Only the fresh executor result is valid. | Existing executor and reuse assertions. | -| S9 | Independent native input versus trace-primed input. | Passed closure to native discovery. | Only independent native input is valid. | `test_native_review_does_not_recurse` and existing independence assertions. | -| S10 | Disconnected component calls in one check versus one entry-triggered causal traversal. | Named check body through the production hops. | Repackaged component proof fails. | The forward fixture and focused trace test. | -| S11 | Deterministic callback or async continuation versus an invented synchronous-stack rule. | Real entry through a check-driven continuation to the terminal owner. | The causal async path can pass. | The forward fixture and focused trace test. | - -One named check can be parameterized. Each proof case must traverse the complete causal path. - -## Implementation - -Add the causal traversal and seam-placement requirements only to Owner Composition. Add distinctive `cpk-rule-guard` text only in that owner. - -Make Scenario Discrimination bind every path fact in a closure row to one exact named check. It must apply Owner Composition without copying the traversal rule. - -Add these fields to the existing trace result: - -- `production_hops`: every in-scope production hop in order. -- `one_check_traverses_complete_path`: `true` only when one named check proves the causal traversal. -- `external_boundary_seams`: permitted external seams, or an empty list. -- `replaced_in_scope_hops`: an empty list for a valid row. - -Keep the existing entry, gate, enforcement, terminal, check, and result fields. Do not add separate required-hop and observed-hop lists. - -A false, unknown, missing, or unsupported continuity value fails closure. A missing production hop also fails closure. A nonempty `replaced_in_scope_hops` value fails closure. The fresh executor must add the exact missing path check to `missing_tests`. - -Extend the two existing focused tests and the CPK-045 forward fixture. Do not add a test framework or another fixture. - -## Semantic Subtask - -CP1 is the only subtask. Its observable outcome is a trace rule that rejects proof assembled from component execution. - -Owner Composition is the primary owner. Scenario Discrimination and the trace result are direct consumers. The allowed change boundary includes these owners, the two focused tests, the forward fixture, version references, task documentation, and checksums. - -CP1 depends on the accepted Plan history records and no earlier checkpoint. Its focused validation uses the transition-closure, trace-closure, recursion, and unique-owner tests. Its checkpoint review covers the complete CPK-053 candidate from the task base. The local commit contains the complete reviewed task. - -## Validation - -Run the focused unit tests for transition closure, trace closure, native-review recursion, and unique rule ownership. Run the clean-context forward fixture. Then run `./run-tests.sh`, shell and PowerShell syntax checks, `git diff --check`, and `sha256sum --check MANIFEST.sha256`. - -This task changes static toolkit rules. Use deterministic checks and native review. Do not use semantic trace closure for this candidate. - -Use one reviewed checkpoint because the task has one coherent correction. After a clean review, commit the candidate. Install that exact commit in the live environment. Require Doctor to report version `0.23.7` and `Result: ready`. Do not publish without a separate request. - -## Interfaces and Dependencies - -The trace-closure JSON gains four evidence fields. No executable API, dependency, service, parser, or runtime state is added. - -## Prior Plan Reconciliation - -The accepted Plan record is carried without supersession. CPK-052 remains authoritative for accepted-inventory-only trace semantics, fresh execution, reuse-only validation, and native-review independence. diff --git a/docs/plans/cpk-054-internal-plan-history.md b/docs/plans/cpk-054-internal-plan-history.md deleted file mode 100644 index 19cf075..0000000 --- a/docs/plans/cpk-054-internal-plan-history.md +++ /dev/null @@ -1,92 +0,0 @@ -# Keep one versioned Plan history - -This ExecPlan follows [PLANS.md](../../.agent/PLANS.md). It records the CPK-054 storage correction. - -## Purpose - -Completed Plan summaries must stay versioned in `.agent/plan-history/` so another device receives them through Git. Stop creating additional files beside specifications. After an untracked summary moves into a task worktree, a later primary-checkout hook must not recreate the same event and content. - -The user requested this change on 2026-09-05. The user excluded cleanup of other repositories and retained the generated roadmap view as an exception. A later request authorized publication and updating the host installation. - -## Context and isolation - -`save_plan` in `assets/hooks/session_start.py` owns storage. Direct `Stop` events supply a completed message. `UserPromptSubmit`, `SessionStart`, and `SessionEnd` supply it through the transcript reader. The exact message contains specification markers, so associations survive without sibling files. `write_record` already compares event identity and bytes before writing, but only in the current worktree. - -`assets/skills/plan-history/SKILL.md` owns discovery and worktree handoff. `tests/test_kit.py` contains real hook subprocess checks. The README describes the storage behavior. - -Use branch `fix/plan-history-storage`, based on `main` at `2115b270a50ead31f7071f5d95b5210ba7c6b290`. The earlier, reviewed roadmap instruction change remains in the same working tree and complete review candidate. There is one writable stream and no worktree transfer for this task. - -## Product boundary and Decision Log - -Apply [Scope boundaries](../../assets/skills/design-preflight/references/scope-boundaries.md) and [Supported model](../../assets/skills/design-preflight/references/supported-model.md). Normal use has one Codex writer, primary and linked Git worktrees, and ordinary files. Normal tracked copies in different checkouts and devices remain necessary; redundant generated records are the defect. - -The storage destination, duplicate suppression, discovery instructions, affected checks, and this repository's legacy cleanup are `composes`. Transcript parsing, marker validation, capture timing, roadmap generation, and hook output formats remain `opaque`. Other repositories, scans of inactive branches, automatic migration, and new storage formats are outside this task. Publication and host installation use the existing delivery commands. - -Decision: publish version `0.23.8`, a patch increment from committed version `0.23.7` for the storage correction. Run `./install.sh` and require `./doctor.sh` to report `Result: ready` before publication. - -Decision: retain the existing versioned directory and remove the sibling writer. Do not use local-only Git metadata storage. - -Decision: extend the existing immutable writer's search across active worktrees reported by `git worktree list --porcelain -z`. An identical event already retained in another worktree requires no new file. A new event or different response bytes still requires preservation. Do not add a shared index, database, dependency, or new command. - -Decision: keep one-way handoff into the task worktree, then let Git carry the committed record to main. Do not manually copy history back to main. Do not remove ordinary tracked records from other checkouts. - -Decision: during this repository's cleanup, reuse a central record only when its event identity and bytes match. Otherwise copy the legacy record centrally and verify its bytes before removing the old path. Retain timestamps, event keys, and collision suffixes. Remove only the specification-stem prefix from a migrated filename. Update references outside immutable summaries. - -## Prior plan reconciliation - -Record: `.agent/plan-history/plan-summary.20260822T050100617085Z.fd7dfe4c94e461a1824112794d31e1372d316ccf79eed8a3937d2754c1157e40.md` -Status: superseded -Reason: The user requested one internal, versioned summary location. -Replacement: Save repository summaries only centrally and retain associations in their unchanged markers. -Scope: specification-sibling creation only. Capture timing, exact bytes, identity, and global fallback remain carried. - -Record: `.agent/plan-history/plan-summary.20260825T173129857080Z.a3ee26a1802fb85c5a0a100ccb3c33c1a6fff358bd20b65636adc61f8d0de377.md` -Status: superseded -Reason: The user reported duplicate summaries in main and requested a single versioned location. -Replacement: Hand off applicable untracked central records into the task worktree, suppress exact replay across active worktrees, and commit them there. Git integration replaces manual copying to main. -Scope: required sibling copies and duplicate replay. The byte-verified handoff and protection of unrelated records remain carried. - -These decisions supersede the storage-location clauses in completed CPK-036 and CPK-040 specifications. Their historical descriptions remain evidence. Other completed task records do not add scope to this correction. - -## Boundary inventory and Scenario Proof - -Apply [Scenario discrimination](../../assets/skills/design-preflight/references/scenario-discrimination.md), [Owner composition](../../assets/skills/design-preflight/references/owner-composition.md), and [Full-set results](../../assets/skills/design-preflight/references/full-set-results.md). - -| Source clause | Disposition | -| --- | --- | -| User: internal organization and versioned cross-device history; old sibling creation in `save_plan` and Plan History capture/association instructions | B1 | -| User: avoid redundant main/worktree copies; existing event-key and exact-byte equality in `write_record`; handoff directions | B2 | -| Existing immutable writer: preserve distinct identities and different-content collisions; preserve non-Git capture using the same writer | B3 | -| User: one place for summaries; Plan History complete discovery, immutable evidence, and commit instructions | B4, non-runtime | -| Existing marker validation: missing markers, sole or mixed none, all valid/invalid specification targets | Opaque; keep validation and warning regressions | -| Existing envelope, newest-turn selection, transcript completion, capture timing, and hook output formats | Opaque; keep existing regressions | -| Reconciliation order, explicit supersession, immutable completed checkpoints, and partial-history stop | Opaque; unchanged | -| Roadmap generation and publication implementation | Opaque; unchanged | -| Other repositories, concurrent writers, hostile markers, bare repositories, and inactive-branch scanning | Outside task scope | -| Later user request: publish and update the host environment | Existing publication and installation workflow; no new runtime boundary | -| Readme and exact tests describing the storage facts | Supporting documentation/checks, not additional boundaries | - -| Boundary | Discriminator and contrast | Production path and terminal oracle | Exact named check | -| --- | --- | --- | --- | -| B1 | One or multiple valid specification markers versus none | Each supported hook reaches `save_plan` and `write_record`: exact central record, no specification sibling, idempotent replay. Commit and clone retain that same captured record. | `test_plan_history_stays_internal_for_every_event` | -| B2 | Primary capture before handoff versus replay after the same event/bytes exists only in a linked task worktree | Each hook captures in primary; byte-verified handoff and task commit precede a primary replay. Worktree enumeration and the shared writer suppress regeneration. Git merge retains the single tracked record and clean status. | `test_plan_history_handoff_then_primary_replay` | -| B3 | Exact repeated identity/content versus changed bytes or new identity, including duplicate prefixes followed by different content | Each hook reaches the same writer across active worktrees. Exact repeats add nothing; different content and identities survive. A replay of a collision also adds nothing. Outside Git, only the existing cwd-specific fallback participates. | `test_plan_history_cross_worktree_identity` and `test_plan_history_uses_global_storage_outside_git` | -| B4 | Legacy sibling plus identical central record versus a unique legacy record | Non-runtime cleanup retains one central copy of each event/content and all distinct-content evidence. Direct discovery still includes unmigrated legacy records. | Exact Git-source/destination byte comparison and `test_plan_history_is_immutable_and_complete` | - -Every hook case means direct Plan-mode Stop, UserPromptSubmit, SessionStart for resume/compact/clear, and SessionEnd. Named tests invoke the real hook subprocess; they do not replace an in-scope runtime hop. Repository-scope checks include nested cwd and a linked worktree path containing spaces. The supported handoff acts on retained state before the later replay. - -## Implementation and validation - -Use one atomic subtask, CP1. Remove the sibling write loop in `save_plan`. Obtain active worktree history directories with native Git and pass them to the existing writer for equality and collision searches. Keep new writes in the current repository's central directory and retain the current global fallback outside Git. Validate markers before deciding whether an event is already retained, so warnings remain observable. - -Change the skill to create central records only, link later specifications to those records, and hand off only toward the task worktree. Preserve legacy discovery and document safe, explicit cleanup. Move this repository's unique legacy summaries centrally and remove verified duplicates. Correct references and the README. - -Run the new central-storage check before the runtime edit. Then run all named Scenario Proof methods with `PYTHONPATH=tests python3 -m unittest test_kit.PlanHistoryHookTests. -v`. Run `./run-tests.sh`, compare migrated record bytes against the task-base Git blobs, run `git diff --check`, and update and verify `MANIFEST.sha256`. Keep exact commands and results in `.agent/test-results/cpk-054-internal-plan-history.md`. On this host, use `TMPDIR=/var/tmp` because a pre-existing invalid `/tmp/.git` marker prevents a valid outside-Git fixture. - -Finalize documentation, run the required fresh trace verifier for B1-B3, then run native review of the complete candidate. B4 receives deterministic validation and native review. CP1 has one full-review boundary with no intermediate commit. Close CPK-054 after a clean result. Install the reviewed candidate, verify Doctor readiness, and publish through the existing publication workflow. - -## Idempotence and dependencies - -Reuse the immutable writer's event key and collision suffix. Search every active worktree without copying its records. Cleanup must not overwrite a different destination or remove the last verified copy. A failed operation stops and reports its result. No new dependency, index, service, migration command, or mutable task record is needed. - -Revision: user clarification retained versioned history; the source-confirmed handoff/replay path adds cross-worktree duplicate suppression to central-only capture. diff --git a/docs/plans/cpk-055-native-ponytail.md b/docs/plans/cpk-055-native-ponytail.md deleted file mode 100644 index 5937229..0000000 --- a/docs/plans/cpk-055-native-ponytail.md +++ /dev/null @@ -1,96 +0,0 @@ -# CPK-055 — Install the official Ponytail plugin - -This specification follows `.agent/PLANS.md`. It defines two independent checkpoint boundaries. - -## Purpose - - -Install all official Ponytail features through Codex. Users control modes and persistent defaults through the upstream plugin. The toolkit no longer changes modes at phase boundaries. Codex exposes the six skills through its skill interface, including `@ponytail-review`; a slash-menu entry is not promised. - -## Context and orientation - - -`kit.py` currently downloads only Ponytail's main skill and license through `UPSTREAM_SKILLS` and `upstream.lock.json`. `assets/AGENTS.block.md`, the lifecycle implementation-mode reference, and `assets/hooks/session_start.py` impose toolkit mode choices. The native plugin includes six skills and SessionStart, UserPromptSubmit, and SubagentStart hooks. Codex owns its installation, version, enabled state, and cache. Node.js runs its hooks. - -The task uses branch `task/cpk-055-native-ponytail` from `main` at `c5fe5779d6b5f40a8338b213283b20b2017d3733`, in the existing checkout. Publication is separate from local implementation. Host installation and Doctor follow the complete reviewed candidate. - -## Decision Log - - -- Replace the copied skill with the official native plugin to retain all documented upstream features. -- Preserve existing official plugin versions, settings, and disabled state. Codex owns updates and removal, including installations first created by this toolkit. -- Reject foreign marketplace sources and unowned standalone skills before native writes. Remove a legacy skill only after successful native installation or reuse and proof of prior manifest ownership. -- Require Node.js and native plugin-command support before changing an existing installation. Do not install Node.js, implement aliases, modify upstream bytes, or grant hook trust. -- Keep the existing shared subprocess helper and explicit selected `CODEX_HOME`. Do not add a plugin ownership ledger or mode state. -- Document complete removal on POSIX and Windows, including retained plugin data, shared settings, RepoWise, uv, repository indexes, and Plan history. - -## Plan deviations and reconciliation - - -The accepted source is [.agent/plan-history/plan-summary.20260906T145108959420Z.4ca59f1efb35d2fec6091bc88b5848bb2e50226576f0a493f9ec85ed1838c57b.md](../../.agent/plan-history/plan-summary.20260906T145108959420Z.4ca59f1efb35d2fec6091bc88b5848bb2e50226576f0a493f9ec85ed1838c57b.md). Its decisions are carried. The user's explicit plugin-only mode choice supersedes phase-based mode selection in [CPK-028](cpk-028-phase-scoped-minimalism.md) and [CPK-029](cpk-029-plan-mode-hook.md). Their other requirements remain carried; their historical contents remain unchanged. Earlier Plan records retain their unrelated decisions, including installation ownership and central Plan capture. - -Record: [.agent/plan-history/plan-summary.20260824T164719361941Z.f1479c9effab9071b8ccaa86dce1dbee407b79647c6bb7d542aea8c75caae32b.md](../../.agent/plan-history/plan-summary.20260824T164719361941Z.f1479c9effab9071b8ccaa86dce1dbee407b79647c6bb7d542aea8c75caae32b.md) - -Status: superseded - -Scope: its retained CPK-028 authority for automatic Ponytail mode selection only. - -Reason: the user explicitly selected plugin-only mode ownership in the accepted CPK-055 Plan. - -Replacement: the upstream plugin and user selections control modes. All unrelated retained decisions remain carried. - -## Surprises & Discoveries - - -Native Codex refuses plugin inspection when the selected `CODEX_HOME` directory does not exist. Fresh installation creates that directory before inspection. Existing installation files remain unchanged during prerequisite checks. - -## Product boundary - - -Apply [Scope boundaries](../../assets/skills/design-preflight/references/scope-boundaries.md) and [Supported model](../../assets/skills/design-preflight/references/supported-model.md). The accepted Plan and explicit user decisions define the product result. Toolkit installation, migration, Doctor, and managed hook output are in-scope owners. Native Codex commands and the unmodified Ponytail package are external owners. Tests may substitute only those opaque commands and network providers. User hook trust remains manual. Toolkit uninstall and purge retain native plugin resources for fresh and pre-existing installations alike. - -## Scenario Proof - - -Apply [Scenario discrimination](../../assets/skills/design-preflight/references/scenario-discrimination.md) and [Owner composition](../../assets/skills/design-preflight/references/owner-composition.md). The following accepted inventory maps every behavior clause. CP1 covers B2 and B9; CP2 covers the remaining runtime rows and B10 documentation. Upstream model quality is opaque. Publication is outside this task. - -| Boundary | Discriminator and minimal contrast | Production path and required oracle | Named check | -| --- | --- | --- | --- | -| B1 | Complete native plugin versus copied main skill | Install through native commands; six skills and all three hook declarations exist | `test_fresh_install_registers_complete_plugin`, isolated native smoke | -| B2 | Plugin active versus off, with toolkit phase changes | Managed hook and static routes never select a mode | `test_plan_prompt_preserves_plugin_mode_and_history`, `test_ponytail_modes_have_only_upstream_owner` | -| B3 | Manifest-owned legacy skill versus unowned same path | Actual install removes only recorded legacy skill after native success; conflict preserves user data | `test_legacy_skill_migration_requires_recorded_ownership` | -| B4 | Absent versus existing official plugin; foreign versus official marketplace | Actual install creates absent plugin, preserves existing version/settings/enabled state, rejects foreign source before writes | `test_existing_official_plugin_is_reused`, `test_foreign_marketplace_is_preserved` | -| B5 | Fresh versus pre-existing native installation | Install, reinstall, uninstall and purge retain native resources and settings | `test_native_plugin_survives_reinstall_and_uninstall` | -| B6 | Selected Codex home versus process-default home | Install and Doctor use selected home; uninstall follows recorded toolkit destinations without native removal | `test_plugin_commands_use_selected_codex_home` | -| B7 | Native plugin and Node.js versus legacy-only or missing prerequisites | Doctor rejects missing requirements; install independently rejects missing Node.js and unsupported native commands before old skill/hooks/config/manifest changes | `test_doctor_requires_native_plugin_and_node`, `test_missing_prerequisites_preserve_existing_installation` | -| B8 | Plugin installation versus user hook approval | Actual install configuration and output preserve manual trust | `test_fresh_install_registers_complete_plugin` | -| B9 | Plan versus ordinary prompt, and session lifecycle | Configured installed hook preserves history and reminder without a mode directive; session announcement remains | `test_plan_prompt_preserves_plugin_mode_and_history`, existing Plan and SessionStart checks | -| B10 | Toolkit removal versus full optional component cleanup | README documents ordered POSIX and Windows cleanup and retained state | Documentation inspection and native review | - -The preflight challenger identified two additional test obligations within B4 and B7: foreign marketplace rejection and independent prerequisite failures through actual installation. Both are included above. All accepted clauses are mapped or explicitly opaque or outside scope. No unresolved contract gap remains. - -## Plan of work - - -CP1 removes the managed Ponytail route, automatic mode instructions, and prompt-hook `normal mode` output. Retain test-scope requirements, challenger reasoning, Plan capture, planning reminders, and other hooks. Update the installed-hook and rule-owner tests in `tests/test_kit.py`. Correct the README's prompt-hook statement. This checkpoint's owner is the managed hook and lifecycle reference. Its review and local commit cover only this boundary and its specification. - -CP2 changes `kit.py` to inspect `codex plugin marketplace list --json` and `codex plugin list --marketplace ponytail --json`. Pass the selected Codex home to every native command. Add the official `DietrichGebert/ponytail` marketplace and `ponytail@ponytail` plugin only when absent. Validate prerequisites and ownership before mutation. Remove Ponytail from copied upstream skills and add its legacy name to obsolete skills. Put the native integration checks in `tests/test_ponytail.py`. Update Doctor, the lock descriptor, README, CODEX-INSTALL-PROMPT.md, THIRD_PARTY.md, and checksums. This checkpoint depends on CP1 and covers native lifecycle, migration, and cleanup documentation. - -## Concrete steps and acceptance - - -From the repository root, run focused checks with `TMPDIR=/var/tmp python3 -m unittest discover -s tests -p 'test_*.py' -k `. CP1 must preserve the Plan reminder and emit no mode choice. CP2 must meet each row's terminal oracle through the actual toolkit path. Run `TMPDIR=/var/tmp ./run-tests.sh` for the complete suite. `/var/tmp` avoids an unrelated invalid `/tmp/.git` marker on this host. - -Use an isolated Codex home for a real native installation smoke check. Confirm all six skill files and three hook events from its native catalog and package. Exercise full, lite, ultra, off, status, persistent defaults, and lifecycle hooks with isolated upstream state. Preserve upstream package bytes. Complete checkpoint trace verification and native reviews, followed by the final complete native review. Then run `./install.sh` and `./doctor.sh` on the host; Doctor must report `Result: ready`. - -## Idempotence and removal - - -Repeated installation reuses official native resources without upgrades or forced enablement. Native command errors stop the operation. Complete installation transactionality remains outside the supported model. Prerequisite and ownership conflicts must occur before changes to existing installation data. - -README cleanup instructions first remove repository integrations, then purge toolkit files. Optional upstream state cleanup precedes native plugin removal because removal deletes its cache. The upstream uninstall script does not remove Codex's `plugins/data/ponytail-ponytail` state. Document that state separately, plus shared Ponytail configuration and its effect on other clients. Then describe native plugin and marketplace removal, optional RepoWise and uv removal, and retained Plan history and indexes. Do not perform cleanup in other repositories. - -## Artifacts - - -Keep detailed command, trace, and review results in `.agent/test-results/cpk-055-native-ponytail.md`. This ignored record is not part of the product specification. Regenerate `MANIFEST.sha256` for each review candidate. No new dependency, wrapper, or custom state format is needed. diff --git a/docs/plans/cpk-056-interviews-and-assessment.md b/docs/plans/cpk-056-interviews-and-assessment.md deleted file mode 100644 index cc93498..0000000 --- a/docs/plans/cpk-056-interviews-and-assessment.md +++ /dev/null @@ -1,135 +0,0 @@ -# Improve interviews and assess rule adherence - -This ExecPlan is the stable implementation specification for CPK-056. Maintain it according to [PLANS](../../.agent/PLANS.md). - -## Purpose - -Codex must ask material questions in prerequisite order and preserve accepted boundaries when a check fails. The toolkit must distinguish its written instruction checks from observed agent behavior. This task adds independent assessment cases and clarifies the existing rule owners. - -## Context and orientation - -The task branch is `task/cpk-056-interviews-assessment`. Its base is reviewed commit `24722f52ed1ab6e23689fb5095d6359d1848bc3b` on `task/cpk-055-native-ponytail`. The isolation form is one task branch. Preserve completed CPK-055 work and unrelated environment files. - -`assets/skills/delivery-lifecycle/references/decision-handoffs.md` owns interviews. `assets/skills/adversarial-review/SKILL.md` owns correction authority. Design Preflight owns its challenger exemption. Owner Composition and Scenario Discrimination own causal proof and scenario evidence. `tests/test_kit.py` verifies their written contracts. The CPK-045 forward fixture contains assessment inputs and expected answers together. - -## Applicable Plan history - -The accepted implementation record is [.agent/plan-history/plan-summary.20260906T184718818166Z.101806a6188b911af737dd47187082418727ed7042831dd332d77360d1cb6b93.md](../../.agent/plan-history/plan-summary.20260906T184718818166Z.101806a6188b911af737dd47187082418727ed7042831dd332d77360d1cb6b93.md). - -The prior interview record is [.agent/plan-history/plan-summary.20260906T161604059175Z.811836c214ecc89cb39c692f4366e4e79e56a698bf0d01445feb86fcd2c725f4.md](../../.agent/plan-history/plan-summary.20260906T161604059175Z.811836c214ecc89cb39c692f4366e4e79e56a698bf0d01445feb86fcd2c725f4.md). - -Carry these inherited records and their existing recorded supersessions: - -- [CPK-041](../../.agent/plan-history/plan-summary.20260822T065923051937Z.4415ee79c8b0327ba824768113192b4f60662d355fb4931876ec995a214a5526.md): material-choice explanations and routine exclusions. -- [CPK-044](../../.agent/plan-history/plan-summary.20260824T135017227348Z.7cfbec79d5ce39f1a1d436a31dccfe0669c616f252b6793d4b90dc2b34ad13d6.md): correction authority and native review. -- [CPK-045](../../.agent/plan-history/plan-summary.20260824T164719361941Z.f1479c9effab9071b8ccaa86dce1dbee407b79647c6bb7d542aea8c75caae32b.md): behavioral boundaries, as subsequently reconciled. -- [Final CPK-046](../../.agent/plan-history/plan-summary.20260825T002911279202Z.940432714b78524077326cf1dea7571142fa6038e878a2fb7e884024bc8775a8.md): strict simplification and final native review. -- [Final CPK-047](../../.agent/plan-history/plan-summary.20260825T173129857080Z.a3ee26a1802fb85c5a0a100ccb3c33c1a6fff358bd20b65636adc61f8d0de377.md): bounded source packets and stable challenger identity. -- [CPK-053](../../.agent/plan-history/plan-summary.20260901T024803899174Z.f5becdd56d889aba50bf375a29ab0feb9012128e404e73e7a664e0243eb5ab8f.md): continuous proof and static-artifact trace eligibility. -- [CPK-055](../../.agent/plan-history/plan-summary.20260906T145108959420Z.4ca59f1efb35d2fec6091bc88b5848bb2e50226576f0a493f9ec85ed1838c57b.md): plugin-controlled Ponytail settings. - -## Prior plan reconciliation - -Record: `.agent/plan-history/plan-summary.20260906T161604059175Z.811836c214ecc89cb39c692f4366e4e79e56a698bf0d01445feb86fcd2c725f4.md` - -Status: superseded - -Reason: The user requested a combined interview and assessment implementation. - -Replacement: Preserve all interview requirements and relay deferral. Add independent assessments and the correction and proof clarifications in this specification. - -Scope: Unfinished CPK-056 work. - -The accepted combined record is carried. Completed specifications and checkpoint commits remain historical evidence. - -## Decision log - -- Decision: Use saved cases, a separate grader, and fresh agents during this task. - Rationale: A new runner or evaluation framework is unnecessary for the bounded comparison. -- Decision: Compare actual interview turns and disposable repair actions separately from instruction assertions. - Rationale: Correct wording and self-reported compliance do not establish operational adherence. -- Decision: Keep correction authority and all proof rules in their existing owners. - Rationale: Failure routing must not create a second policy or broaden automatic repair. -- Decision: Retain all numbered and unnumbered CPK-045 obligations under neutral identifiers. - Rationale: The preflight challenger identified source-inventory and equal-result obligations outside the numbered list. -- Decision: Identify the selected rule snapshot and use each disposable case's own RepoWise graph. - Rationale: A fresh conversation can otherwise read installed rules or the wrong repository graph. -- Decision: Permit expected red-to-green work already covered by an accepted plan and preflight. - Rationale: A planned failing test does not revoke existing implementation authority. - -## Product boundary and supported model - -Apply [Scope Boundaries](../../assets/skills/design-preflight/references/scope-boundaries.md) and [Supported Model](../../assets/skills/design-preflight/references/supported-model.md). - -The accepted combined Plan supplies the product boundary. Composing owners are Decision Handoffs, correction-entry wording and its finding format, the Design Preflight exemption, Owner Composition, Scenario Discrimination, and their test artifacts. Delivery Lifecycle composes only the route to correction authority. Research First remains the opaque research owner. Native review, severity, runtime trace JSON, install behavior, hooks, and platform internals remain opaque. - -Use normal local files and one writer. Model assessments use disposable local repositories and deterministic provider examples. No real provider accounts are used. Meridian is outside the write boundary. Relay remains deferred. - -The scope ceiling excludes a framework, runner, service, dependency, persistent interview tree, production instrumentation, new automatic approval, and publication. It also excludes hostile grading-file access as a security model. Such access invalidates an assessment; this task does not build a sandbox. - -## Boundary inventory and checks - -These boundaries describe instructions and assessments. They do not create fictional executable production paths. Static artifacts remain outside production trace closure. - -| ID | Required result | Distinguishing check | -| --- | --- | --- | -| B1 | Questions follow investigated facts and settled prerequisites; batches contain at most three independent material questions. | Interview episode A and the existing decision-handoff contract test. | -| B2 | Partial answers and discoveries remove settled or obsolete questions; interviewing ends when the material contract is settled. | Staged replies in A contrast an unresolved prerequisite with a complete contract. | -| B3 | Material choices receive the existing source-backed brief before collection; routine inputs stay concise. | Episode A and `test_material_code_decisions_explain_implementation_before_choice`. | -| B4 | Agent inputs exclude grading answers and comparisons use the intended source snapshot. | Fixture correspondence checks; case-root source/read evidence and before/after transcripts. | -| B5 | Failed-check corrections use the unchanged authority gate; planned implementation retains its existing authority. | Episodes E/F/G and `test_review_findings_need_source_independent_correction_authority`. | -| B6 | Strict simplification exempts only the challenger and only when its existing conditions hold. | Episode G and `test_default_mode_preflight_and_repowise_continue_through_corrections`. | -| B7 | Decision ownership requires source and causal evidence; names and final data alone do not prove it. | Episode B and retained CPK-045 causal-path cases. | -| B8 | External-contract cases have independent evidence or remain unknown; deterministic external seams remain valid. | Episodes C/D and scenario contract assertions. | -| B9 | The assessment retains every existing numbered and unnumbered obligation and isolates its contrasts. | CPK-045 neutral case IDs, separate grader, and complete correspondence checks. | -| B10 | Rules stay single-owned and static artifacts remain ineligible for production trace closure. | Existing owner, route, link, and trace-eligibility tests. | - -The accepted two-phase preflight supplied B1-B10. Both supported Phase 2 findings are incorporated in the decision log. No unresolved contract gap remains. Runtime input-domain and collection-path Scenario Proof are inapplicable to these static toolkit artifacts; the assessment catalog defines its concrete test inputs. - -## Implementation and checkpoints - -CP1 prepares the independent assessment artifacts and captures the baseline. Rewrite `tests/fixtures/cpk045-boundary-forward.md` as neutral inputs. Keep its grading in a separate JSON artifact. Add a CPK-056 case catalog and grading artifact under `tests/fixtures/`. Keep setup and execution instructions with that catalog. Extend `tests/test_kit.py` for complete correspondence and input separation. Freeze cases and the base rule snapshot before running fresh baseline agents. This checkpoint changes no live rule owner. Its local commit follows focused checks and native checkpoint review from the task base. - -CP2 changes only the interview owner and its direct tests. Preserve the required brief while adding prerequisite ordering, independent batches, reassessment, partial-answer handling, and the stopping condition. Run its deterministic checks and the candidate interview episode. Review from CP1 and commit that checkpoint. - -CP3 routes failed checks through the existing correction owner, adds `local-check` to the finding source values, and clarifies expected red tests and strict simplification. Add the decision-ownership example in Owner Composition and independent external evidence in Scenario Discrimination. Link Research First rather than copying its procedure. Extend affected contract tests. Run the remaining candidate assessments and retain their comparison. Review from CP2, commit the checkpoint, and run final native review from the task base. - -## Assessment procedure - -Each case has neutral facts, a task, source artifacts, and separate expected outcomes. The families are A (scripted interview), B (ownership), C (retained provider input), D (provider assumption), E (repair pressure), F (direct arithmetic repair), and G (authorized simplification). The coordinator gives scripted user replies only when the interview reaches the corresponding choice. Never open real user-facing widgets for an assessment. - -Materialize each episode in a distinct temporary Git repository. Copy the selected live-rule tree and applicable relative-link targets into it. Include unchanged external skills named by applicable rules, such as `simple-english` for decision briefs. Keep grading, other cases, other rule versions, prior diagnostics, and preferred fixes outside that directory and outside the prompt. Retain source hashes in the ignored task record. Supply the selected local rule paths as the exercise's toolkit sources; do not use installed copies in their place. - -Prepare only a local RepoWise index with: - - repowise init --yes --no-prose --embedder mock --no-editor-setup --no-save-key --no-workspace - -Scope lookups with the existing CLI's `--path --no-workspace` options. Do not use the parent repository's MCP graph. Inspect actual reads and graph identity when grading. Wrong-version reads, grading access, and unavailable dependencies make the episode inconclusive. - -Use a fresh agent with `fork_turns="none"` for each case and rule version. Hold the configured model, reasoning, ordinary implementation mode, tools, and Ponytail state constant. The coordinator grades source-backed answers and actual actions, not just verdict fields. Only E and F permit repository edits, and only inside their disposable roots. There is at most one write-capable assessment agent at a time. G is a classification check, not evidence that a complete operational workflow ran. - -Run one baseline and one candidate attempt for each fixed case. Preserve failures, ties, and inconclusive outcomes. Do not repeat unchanged attempts to obtain a pass. A changed case invalidates both sides of its comparison. An interview result can be reused only if its selected source packet and case are unchanged. - -Use short, dated authoritative references for external examples: [Microsoft Graph user lookup](https://learn.microsoft.com/en-us/graph/api/user-get?view=graph-rest-1.0) and [delta query](https://learn.microsoft.com/en-us/graph/delta-query-overview). Label synthetic identities and retained examples. Offline cases do not prove live Graph compatibility. - -## Validation and acceptance - -Run focused tests from the repository root with: - - python3 -m unittest discover -s tests -p test_kit.py -k material_code_decisions - python3 -m unittest discover -s tests -p test_kit.py -k assessment - python3 -m unittest discover -s tests -p test_kit.py -k boundary_trace_closure - python3 -m unittest discover -s tests -p test_kit.py -k correction_authority - python3 -m unittest discover -s tests -p test_kit.py -k default_mode_preflight - -Run `./run-tests.sh`, applicable shell and PowerShell syntax checks, rule-owner and link checks, `sha256sum --check MANIFEST.sha256`, and `git diff --check`. Regenerate checksums after substantive tracked changes. Static tests must preserve the old obligations and verify the new contract and fixture wiring. - -Candidate assessment cases must satisfy their retained expectations. Classify each outcome as a correct action, correct stop, unnecessary stop, wrong action, or inconclusive. Failed required candidate cases remain unresolved validation and use the existing correction gate. Never relax the rubric to obtain a pass. Report ties honestly and claim no statistical reliability rate. - -Finalize documentation before review. Use the existing [Adversarial Review](../../assets/skills/adversarial-review/SKILL.md) checkpoint and final sequence. Install the reviewed candidate and run Doctor. The default suite, installer, and Doctor gain no model calls. Keep version selection and publication separate. - -## Artifacts and interfaces - -Keep detailed evidence in `.agent/test-results/cpk-056-interviews-and-assessment.md`. It includes snapshot identities, input hashes, actual transcripts, disposable diffs, checks, grading, and native review evidence. Do not stage this record. - -The finding source vocabulary gains `local-check`. Assessment responses use neutral case identifiers, verdicts, evidence, and proposed actions. No runtime API, CLI, trace schema, dependency, or persistent product state changes. diff --git a/docs/plans/cpk-057-review-and-astra-guidance.md b/docs/plans/cpk-057-review-and-astra-guidance.md deleted file mode 100644 index 3d05d48..0000000 --- a/docs/plans/cpk-057-review-and-astra-guidance.md +++ /dev/null @@ -1,117 +0,0 @@ -# Separate review from testing and complete Astra guidance - -This ExecPlan is the implementation specification for CPK-057. Maintain it according to [PLANS](../../.agent/PLANS.md). - -## Purpose - -Reviewers inspect source and existing evidence without executing tests. Implementation completes validation before review. The toolkit also adds missing Astra guidance for authorized work, instruction precedence, communication, and useful delegation. - -## Context and orientation - -The task branch is `task/cpk-057-review-astra-guidance`. Its base is `a33c806c4187f89a2fefa73c913146f3f07858b8` on `task/cpk-056-interviews-assessment`. Use one branch and one implementation writer. Preserve completed checkpoints and unrelated environment files. - -Adversarial Review owns reviewer behavior. Delivery Lifecycle owns implementation validation and authorized task completion. Coordination owns agent roles and instruction use. Docs Maintainer owns the additional prose guidance. Toolkit Maintainer owns the instruction conflict audit. Publication transports the canonical reviewer instructions into hosted requests. - -The direct instruction checks are in `tests/test_kit.py`. The native review command remains `codex review --commit `. The installed skills and existing AGENTS routing supply normal local instructions. Hosted reviewers cannot rely on the local installed skills. - -## Applicable Plan history - -The accepted record is [CPK-057](../../.agent/plan-history/plan-summary.20260907T162300226611Z.ddc507f2e3b9b24182cb6abc4eb4782feae98a0c25f8cdc174a2bf8c2c9932a1.md). - -Carry these records and their recorded supersessions: - -- [CPK-041](../../.agent/plan-history/plan-summary.20260822T065923051937Z.4415ee79c8b0327ba824768113192b4f60662d355fb4931876ec995a214a5526.md): material decisions and explanations. -- [CPK-042](../../.agent/plan-history/plan-summary.20260823T052048899607Z.c539b46a7e5fa56092a382fef046fd00d4271c42c4fda8e0f0e2216ce94df122.md): semantic checkpoints. -- [CPK-043](../../.agent/plan-history/plan-summary.20260824T031427928859Z.f30d03e6b396d05f07f5ce7eebc8b8e8b81e2b1cfe8ebc739342a6e444ca6968.md): hosted review before CI. -- [CPK-044](../../.agent/plan-history/plan-summary.20260824T135017227348Z.7cfbec79d5ce39f1a1d436a31dccfe0669c616f252b6793d4b90dc2b34ad13d6.md): native discovery and correction authority. -- [CPK-045](../../.agent/plan-history/plan-summary.20260824T164719361941Z.f1479c9effab9071b8ccaa86dce1dbee407b79647c6bb7d542aea8c75caae32b.md): boundary inventory, as subsequently reconciled. -- [Final CPK-046](../../.agent/plan-history/plan-summary.20260825T002911279202Z.940432714b78524077326cf1dea7571142fa6038e878a2fb7e884024bc8775a8.md): final native review and bounded scope. -- [Final CPK-047](../../.agent/plan-history/plan-summary.20260825T173129857080Z.a3ee26a1802fb85c5a0a100ccb3c33c1a6fff358bd20b65636adc61f8d0de377.md): bounded preflight and publication. -- [CPK-048](../../.agent/plan-history/plan-summary.20260825T183857932150Z.47ec1ac118b8c6c23f961b4099708aacc7031581a744bc389e6795e1c2007796.md): focused repository overrides. -- [CPK-053](../../.agent/plan-history/plan-summary.20260901T024803899174Z.f5becdd56d889aba50bf375a29ab0feb9012128e404e73e7a664e0243eb5ab8f.md): continuous proof and static-artifact eligibility. -- [CPK-055](../../.agent/plan-history/plan-summary.20260906T145108959420Z.4ca59f1efb35d2fec6091bc88b5848bb2e50226576f0a493f9ec85ed1838c57b.md): upstream Ponytail ownership. -- [Final CPK-056](../../.agent/plan-history/plan-summary.20260906T184718818166Z.101806a6188b911af737dd47187082418727ed7042831dd332d77360d1cb6b93.md): interviews and correction entry. - -This is new corrective work. Do not rewrite completed specifications or their checkpoint commits. - -## Decision log - -- Decision: Keep the existing native review command and AGENTS route. - Rationale: The [CLI reference](https://learn.chatgpt.com/docs/developer-commands?surface=cli) makes custom prompts incompatible with `--commit`. A configuration override can replace user instructions. -- Decision: Carry the user's actual no-tests requirement in this task's synthetic commit intent. - Rationale: The first review precedes installation of the changed skill. The intent remains a requirement, not a coordinator verdict. -- Decision: Include the canonical execution restriction in each hosted review request. - Rationale: [Hosted review supports additional request instructions](https://learn.chatgpt.com/docs/third-party/github). Local installed skills are not a demonstrated hosted instruction source. -- Decision: Use bounded proactive delegation with the existing role limits. - Rationale: The user selected this adaptation of the guide's broader delegation example. -- Decision: Leave delegation behavior proof to another project. - Rationale: The user's later instruction explicitly removes local delegation assessments from this task. Normal repository checks remain applicable. - -## Product boundary and preflight - -Apply [Scope Boundaries](../../assets/skills/design-preflight/references/scope-boundaries.md) and [Supported Model](../../assets/skills/design-preflight/references/supported-model.md). - -The composing owners are the reviewer execution boundary, lifecycle validation and autonomy, coordination, prose guidance, instruction maintenance, hosted request wording, and their direct checks. Review modes, correction authority, severity, material-decision contracts, runtime trace rules, installation, hooks, and external skills remain opaque. - -Use normal local files and Git. The scope excludes new skills, frameworks, wrappers, runtime configuration, model settings, dependencies, external-project work, and publication. Do not add delegation assessments or repeat CPK-056 cases. - -These are static instruction boundaries. Production entry points and runtime Scenario Proof are inapplicable. Use deterministic instruction checks and the required native reviews. - -| Boundary | Required result | Contrast and check | -| --- | --- | --- | -| B1 | Reviewers inspect source without executing or delegating tests. | Read test bodies versus execute them; direct review contract checks and actual native tool activity. | -| B2 | Implementers validate before review and repeat checks only for a concrete reason. | Unchanged validated candidate versus an authorized correction; lifecycle and correction contract checks. | -| B3 | Authorized work continues within the active mode and accepted scope. | Routine judgment versus an unresolved material choice; lifecycle and existing handoff checks. | -| B4 | User instructions outrank skill guidelines; skill-caused stops identify their exact source. | Explicit applicable requirement versus inferred approval; instruction-use checks. | -| B5 | Ordinary prose is clear while required formats and technical literals remain intact. | An explanation versus required JSON or a decision brief; prose and existing handoff checks. | -| B6 | Delegation targets useful independent work. | Useful parallel assignment versus trivial or dependent work; normal instruction consistency checks only. | -| B7 | Delegation preserves existing role, writer, capacity, and native-review restrictions. | Coordinator authority versus restricted child roles; existing coordination checks. | -| B8 | Each live rule stays in its owner with valid routes. | A canonical rule versus a copied or broken route; owner and link checks. | -| B9 | The task makes no claim of validated delegation behavior. | Instruction consistency versus observed behavior; task scope and final report. | - -The latest user scope excludes local delegation observations. Keep detailed preflight evidence in the ignored task record. - -## Guide coverage - -The source is the Astra [Prompting best practices](https://developers.openai.com/api/docs/guides/latest-model#prompting-best-practices) section, read on 2026-09-07. Its API features and model settings are outside this task. - -| Advice | Disposition and owner | -| --- | --- | -| Infer action intent and finish authorized work | Add to Delivery Lifecycle, bounded by active mode and scope. | -| Prepare before approval and avoid speculative barriers | Add to Delivery Lifecycle; preserve material choices and correction authority. | -| Audit instruction conflicts | Add the scoped audit to Toolkit Maintainer. | -| User priority and visible skill-caused stops | Add to Coordination. | -| Plain words, active voice, and exact technical content | Already covered by Simple English and Docs Maintainer. | -| Connected prose, useful formatting, and appropriate detail | Add only the missing preferences to Docs Maintainer. | -| Avoid stock phrases and invented labels | Extend Docs Maintainer without copying the external vocabulary guide. | -| Useful delegation | Adapt in Coordination to the user's existing role limits. | -| Legible agent messages | Add to Coordination. | -| Proportionate tests and justified repeats | Add to Delivery Lifecycle; reviewer execution remains prohibited. | -| Focused material questions | Already covered by Decision Handoffs and completed CPK-056. | - -## Implementation checkpoints - -CP1 changes Adversarial Review and the implementation validation paragraph in Delivery Lifecycle. Add a named reviewer execution section. Publication reads that canonical section when it prepares both initial and repeated review requests. Extend the existing review and publication checks. Keep native targets, independent discovery, correction authority, and CI ordering unchanged. Validate the checkpoint, run native checkpoint review from the task base, and create its local commit. - -CP2 adds the remaining collaboration guidance to Delivery Lifecycle, Coordination, Docs Maintainer, and Toolkit Maintainer. Preserve the existing routers and external skill contents. Add only the necessary contract assertions to the existing tests. Review this checkpoint from CP1 and commit it locally. Then run final native review from the task base. - -## Validation and delivery - -Publication version: `0.23.9`. This patch includes the CPK-055 installation fix and the CPK-056 and CPK-057 guidance changes. - -From the repository root, run focused checks before each checkpoint review: - - python3 -m unittest discover -s tests -p test_kit.py -k review - python3 -m unittest discover -s tests -p test_kit.py -k coordination - python3 -m unittest discover -s tests -p test_kit.py -k material_code_decisions - python3 -m unittest discover -s tests -p test_kit.py -k rule_ - -Run the repository-required suite with `./run-tests.sh`. Run applicable shell and PowerShell syntax checks, checksum validation, and `git diff --check`. Update `MANIFEST.sha256` after substantive files are final. Preserve old assertions rather than weakening them for the new guidance. - -Inspect actual native review tool activity after each required review. Require zero executed or delegated tests, source-backed discovery, and unchanged reviewed tree identity. A narrated claim alone does not establish adherence. Use the existing correction gate for an unmet required check. Add no separate review experiment. - -After final clean review, apply normal roadmap and checksum closure. Install the reviewed candidate with `python3 kit.py install --repo .`. Run `python3 kit.py doctor --repo .` and require `Result: ready`. Version selection, push, merge, tags, and releases remain separate. - -## Records and interfaces - -Keep commands, outputs, preflight evidence, reviewer tool activity, and delivery results in `.agent/test-results/cpk-057-review-and-astra-guidance.md`. Do not stage this record. The instruction interfaces change; runtime APIs, CLI options, trace schemas, and installation behavior do not. diff --git a/docs/plans/cpk-058-plan-history-compaction.md b/docs/plans/cpk-058-plan-history-compaction.md deleted file mode 100644 index 9e5b1c3..0000000 --- a/docs/plans/cpk-058-plan-history-compaction.md +++ /dev/null @@ -1,120 +0,0 @@ -# Compact Plan History without losing source evidence - - -This ExecPlan follows [PLANS.md](../../.agent/PLANS.md). It defines the CPK-058 reading-method change. - -## Purpose - - -Large Plan histories must remain usable across context windows and future tasks. An agent reads bounded batches, retains decisions outside conversation context, and reuses verified summaries. It never deletes original Plan captures to reduce context use. - -The user requested this method on 2026-09-15 and selected reusable summaries with links to unchanged originals. Normal context compaction during a read must resume the work instead of triggering the old size-only stop. - -## Context and isolation - - -Use branch `task/cpk-058-plan-history-compaction` from synchronized `main` at `6cc881661646e2bb0c96e07fcf56897e7f7cbf5f`. There is one writable stream. - -`assets/skills/plan-history/SKILL.md` owns history discovery, reading, and reconciliation. Its old instruction stops when the complete applicable history cannot fit in context. `assets/hooks/session_start.py` routes compact-session starts back to this skill. That hook has no context-capacity detector or reading checkpoint. - -`tests/test_kit.py` checks the installed instructions and executes the real hook for startup and compact events. `README.md` describes the user-visible storage behavior. Original captures remain in `.agent/plan-history/` and travel through Git. - -A derived summary is a scoped reading aid. Its source inventory identifies the complete original bytes that it summarizes. It neither replaces those originals nor becomes another implementation plan. - -## Decision Log - - -- Decision: Extend the existing instruction owner with reusable Markdown summaries and bounded reading checkpoints. - Rationale: The failure is an instruction-level stop. A new summarization service, parser, database, or token-limit setting is unnecessary. -- Decision: Store derived evidence in `.agent/plan-history/compacted/`, separately from original captures. Keep mutable reading progress in the ignored task result. - Rationale: Future tasks can reuse evidence through Git without confusing it with captured Plan responses or tracked lifecycle status. -- Decision: Require original source hashes, scope, decision anchors, and explicit fidelity verification before reuse. - Rationale: A hash detects changed bytes but cannot prove that a summary preserved their meaning. A broader task must reopen uncovered scope. -- Decision: Preserve original timestamps, conflict evidence, scoped supersession, and decisions outside a replacement's scope. - Rationale: A newer summary must not silently override an older accepted decision. -- Decision: Split large sources and summaries into bounded reads and save progress after chunks. - Rationale: The method must work when even one original exceeds the comfortable reading budget. Missing checkpoints require evidence reconstruction, not a context-size stop. -- Decision: Use direct original references instead of recursive summary chains. - Rationale: Each summary can be checked and replaced independently when its evidence changes. -- Decision: Validate the procedure as instructions and validate routing through the existing hook subprocess test. - Rationale: No executable semantic compressor is added. These checks cannot establish a general model-fidelity rate or reproduce the user's suspected app interruption. - -## Product boundary and reconciliation - - -Apply [Scope boundaries](../../assets/skills/design-preflight/references/scope-boundaries.md) and [Supported model](../../assets/skills/design-preflight/references/supported-model.md). Normal use includes one writer, local files, Git worktrees, new history records, future tasks, and ordinary context compaction during reads. - -The Plan History reading procedure, derived-summary format, compact routing text, and related checks are `composes`. Original capture timing, marker parsing, event identity, byte-preserving storage, repository setup, publication, and original-record relocation remain `opaque`. No filesystem-fault recovery, concurrent writer coordination, automatic compaction API, model selection, or external-project change is included. - -The user's current request replaces the literal all-originals-in-context requirement and size-only stop. Preserve complete evidence coverage and genuine source-backed conflict stops. This supersedes only those reading restrictions in the current Plan History owner and the unchanged-reconciliation boundary of [CPK-054](cpk-054-internal-plan-history.md). The exact-capture and source-authority contract of [CPK-036](cpk-036-plan-history.md) remains. - -Carry the prior records and their recorded scoped supersessions. CPK-054 remains authoritative for central-only capture and one-way byte-verified handoff. CPK-044 and final CPK-046 remain authoritative for native review. CPK-053 excludes static instruction changes from production trace closure. CPK-055 preserves upstream Ponytail ownership. CPK-056 and CPK-057 retain bounded correction, validation, and communication rules. Their prior assessment work is not repeated here. - -Applicable original records (retain their recorded supersessions): - -- [Original 1](../../.agent/plan-history/plan-summary.20260819T195712262086Z.manual-recovery.md) -- [Original 2](../../.agent/plan-history/plan-summary.20260819T211423672232Z.manual-recovery.md) -- [Original 3](../../.agent/plan-history/plan-summary.20260822T050100617085Z.fd7dfe4c94e461a1824112794d31e1372d316ccf79eed8a3937d2754c1157e40.md) -- [Original 4](../../.agent/plan-history/plan-summary.20260822T065923051937Z.4415ee79c8b0327ba824768113192b4f60662d355fb4931876ec995a214a5526.md) -- [Original 5](../../.agent/plan-history/plan-summary.20260823T052048899607Z.c539b46a7e5fa56092a382fef046fd00d4271c42c4fda8e0f0e2216ce94df122.md) -- [Original 6](../../.agent/plan-history/plan-summary.20260824T031427928859Z.f30d03e6b396d05f07f5ce7eebc8b8e8b81e2b1cfe8ebc739342a6e444ca6968.md) -- [Original 7](../../.agent/plan-history/plan-summary.20260824T135017227348Z.7cfbec79d5ce39f1a1d436a31dccfe0669c616f252b6793d4b90dc2b34ad13d6.md) -- [Original 8](../../.agent/plan-history/plan-summary.20260824T164719361941Z.f1479c9effab9071b8ccaa86dce1dbee407b79647c6bb7d542aea8c75caae32b.md) -- [Original 9](../../.agent/plan-history/plan-summary.20260825T002758364682Z.4eba52594f2ef5bdbe93f4f0ead7b61802e894668d23c749b5af459f65a19437.md) -- [Original 10](../../.agent/plan-history/plan-summary.20260825T002911279202Z.940432714b78524077326cf1dea7571142fa6038e878a2fb7e884024bc8775a8.md) -- [Original 11](../../.agent/plan-history/plan-summary.20260825T172626414955Z.9eaf7888a286b18f69d5a94869ee99522214d23dd715a553664a2041108fced3.md) -- [Original 12](../../.agent/plan-history/plan-summary.20260825T173129857080Z.a3ee26a1802fb85c5a0a100ccb3c33c1a6fff358bd20b65636adc61f8d0de377.md) -- [Original 13](../../.agent/plan-history/plan-summary.20260825T183857932150Z.47ec1ac118b8c6c23f961b4099708aacc7031581a744bc389e6795e1c2007796.md) -- [Original 14](../../.agent/plan-history/plan-summary.20260901T024803899174Z.f5becdd56d889aba50bf375a29ab0feb9012128e404e73e7a664e0243eb5ab8f.md) -- [Original 15](../../.agent/plan-history/plan-summary.20260906T145108959420Z.4ca59f1efb35d2fec6091bc88b5848bb2e50226576f0a493f9ec85ed1838c57b.md) -- [Original 16](../../.agent/plan-history/plan-summary.20260906T161604059175Z.811836c214ecc89cb39c692f4366e4e79e56a698bf0d01445feb86fcd2c725f4.md) -- [Original 17](../../.agent/plan-history/plan-summary.20260906T184718818166Z.101806a6188b911af737dd47187082418727ed7042831dd332d77360d1cb6b93.md) -- [Original 18](../../.agent/plan-history/plan-summary.20260907T162300226611Z.ddc507f2e3b9b24182cb6abc4eb4782feae98a0c25f8cdc174a2bf8c2c9932a1.md) - -## Boundary inventory and checks - - -| Boundary | Required distinction | Check | -| --- | --- | --- | -| B1 | Small versus oversized history, including a decisive clause beyond the first chunk of one original | Existing history contract test requires intra-record chunks, complete coverage, and no unread-tail planning | -| B2 | Uninterrupted versus compacted reading, including a partial record and a missing checkpoint | Existing hook subprocess test checks compact routing; history contract checks saved ranges, hash validation, and reconstruction | -| B3 | Valid future-task summary versus new, changed, incomplete, or out-of-scope evidence | History contract checks direct originals, scope, verification, stale-evidence rereading, and supplemental original links | -| B4 | Empty or singleton inventory versus duplicate prefix followed by a distinct record or collision | Preserve full discovery and event-plus-byte identity; check separate derived-summary discovery and final inventory enumeration | -| B5 | Explicit supersession versus unresolved cross-batch conflict; scoped replacement versus unaffected decisions | Preserve canonical supersession fields, original order, both conflict sources, and carried decisions outside scope | - -The fresh preflight challenger independently derives the source clauses and these distinctions, then checks the concrete procedure. These are instruction boundaries, not a new executable history subsystem. - -## Implementation - - -Use one atomic subtask, CP1, with one full native-review and local-commit boundary. Replace the size-only stop and raw-reread wording in the existing Plan History owner. Define the summary fields, reuse validation, bounded reads, resumable working checkpoint, final inventory check, and actual blocking conditions there. - -Change only the compact-session reminder in `assets/hooks/session_start.py` to route to saved reconciliation. Preserve the event dispatch, capture behavior, and output format. Extend the existing history contract and startup/compact tests in `tests/test_kit.py`. Add a short user-facing description beside the current Plan History paragraph in `README.md`. - -Do not add a compression helper or create speculative summaries for unrelated topics. Agents create scoped derived summaries when history size or subsequent reuse needs them. Summary revisions are immutable; verification errors produce new derived evidence while preserving originals. - -## Validation and acceptance - - -From the repository root, run: - - python3 -m unittest discover -s tests -p test_kit.py -k plan_history_is_immutable - python3 -m unittest discover -s tests -p test_kit.py -k session_start_still - ./run-tests.sh - git diff --check - sha256sum --check MANIFEST.sha256 - -Regenerate affected manifest hashes before the checksum check. Run applicable shell and PowerShell syntax checks. Keep full commands, results, source-read inventory, and native review output in `.agent/test-results/cpk-058-plan-history-compaction.md`. - -Walk through five concrete examples against the procedure: a large record with a trailing constraint; compaction after a partial read; a valid reused summary followed by a new record; a duplicate prefix followed by a different-content collision; and a cross-summary conflict with and without a scoped supersession. In each case identify the retained evidence, next read, and whether planning can continue. These examples assess the procedure's completeness, not observed model reliability. - -After clean native review, close the roadmap entry and create the local commit. Install the candidate with `./install.sh`; require `./doctor.sh` to report `Result: ready`. Publication and version selection remain separate. - -## Recovery and dependencies - - -Use existing Git and ordinary Markdown files. Use SHA-256 tools to identify complete source bytes. A missing or stale derived summary permits rereading its original evidence. A changed partial source restarts that source, preserving unaffected coverage. A genuinely unreadable required original or unresolved original-source conflict remains a specific blocker. - -No automatic context reset is required. A completed checkpoint remains usable after one occurs. The agent can partition large reconciliation by topic while retaining cross-topic references in its working record. - -Revision: add reusable derived evidence and resumable reads in response to the user's history-capacity and compaction report. diff --git a/docs/plans/cpk-059-public-pr-release.md b/docs/plans/cpk-059-public-pr-release.md deleted file mode 100644 index 9287525..0000000 --- a/docs/plans/cpk-059-public-pr-release.md +++ /dev/null @@ -1,104 +0,0 @@ -# Publish Plan History through protected pull requests - - -This ExecPlan follows [PLANS.md](../../.agent/PLANS.md) and defines CPK-059. - -## Purpose - - -Release reusable Plan History as version `0.24.0` from a public repository. Changes enter `main` through reviewed pull requests and required CI. A pull request remains draft during Codex review, then readiness starts the required checks. - -## Context and boundary - - -Use `task/cpk-059-public-pr-release` from `3ced26461e9de5e97082d0b7c9e0ce1c0f4fd453`. The repository is `calculatetech/codex-practical-kit`. Its initial main commit is `6cc881661646e2bb0c96e07fcf56897e7f7cbf5f`. - -The user requested public visibility, branch protection, publication, and release. The user selected Codex review plus required CI without an additional human approval. - -Apply [Scope boundaries](../../assets/skills/design-preflight/references/scope-boundaries.md) and [Supported model](../../assets/skills/design-preflight/references/supported-model.md). Workflow configuration, native GitHub settings, version identity, and release delivery are composed here. The existing test launcher, installer, and [CPK-058 implementation](cpk-058-plan-history-compaction.md) remain unchanged owners. - -Normal use is a single writer with GitHub administrator access and a configured Codex GitHub review connection. Preserve unrelated untracked files. No new review service, credentials, platform matrix, cleanup, or production runtime is needed. - -## Decision Log - - -- Decision: Release `0.24.0` under the [version policy](../../assets/skills/publication/references/versioning.md). - Rationale: CPK-058 adds reusable summaries and resumable reads, a new capability beyond `0.23.9`. -- Decision: Use one native GitHub Actions job, `toolkit-tests`. - Rationale: The existing standard-library suite and checksum command provide the needed checks without a new dependency. -- Decision: Trigger only on PR `ready_for_review` targeting `main`, and pushes to `main`. - Rationale: Task pushes and draft creation must not spend hosted CI. Explicit event types exclude the default PR events. -- Decision: Require zero formal approving reviews while retaining a clean Codex review as a publication gate. - Rationale: The repository has one owner. A Codex thumbs-up is evidence for the publication procedure, not a formal GitHub approval. -- Decision: Use native branch protection and squash merges. - Rationale: GitHub already provides required checks, conversations, administrator enforcement, and linear history. - -## Implementation - - -Use one atomic subtask, CP1, with one full native-review and local-commit boundary. Its primary owner is `.github/workflows/ci.yml`; settings and release consume that workflow. - -Create the workflow named `CI`. Its only events are `pull_request` with `branches: [main]` and `types: [ready_for_review]`, plus `push` with `branches: [main]`. Grant only `contents: read`. - -Define `toolkit-tests` on `ubuntu-latest`. Use `actions/checkout@11d5960a326750d5838078e36cf38b85af677262` with `persist-credentials: false`. Use `actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065` with Python `3.11`. Run `./run-tests.sh`, then `sha256sum --check MANIFEST.sha256`. Do not skip steps or tolerate failures. - -Set `kit.py`'s `KIT_VERSION` and its existing test assertion to `0.24.0`. Add one static workflow test in `tests/test_kit.py`. It enumerates all workflow files and rejects extra triggers or conditional check suppression. Update README contribution instructions and distribution checksums. - -After local review, set repository visibility to public and allow only squash merging. Configure main protection with strict required status context `toolkit-tests`, administrator enforcement, resolved conversations, and linear history. Disable force pushes and deletion. Set required approving count to zero, dismiss stale reviews, and require neither code-owner nor last-push human approval. Keep push restrictions null. Read back the actual settings. - -Use the [publication procedure](../../assets/skills/publication/references/publication.md) for local closure, installation, draft review, readiness, squash merge, and integration. The first PR supplies the missing workflow through its merge ref. Prove the complete workflow inventory before the task push. Verify the actual hosted Codex response before readiness. - -After integration and passing main CI, create the unused tag and full GitHub release `v0.24.0` at the exact integrated main commit. Release notes describe reusable summaries, resumable reading, and the PR workflow. Link the versioned README and the full changelog since the previous release, `v0.23.2`. - -## Validation and acceptance - - -Run from the repository root: - - ./run-tests.sh - sh -n doctor.sh install.sh run-tests.sh setup-repo.sh uninstall.sh - git diff --check - sha256sum --check MANIFEST.sha256 - -Require the suite to pass and every checksum to match. Validate workflow structure with an available YAML parser without adding a package dependency. After review, install with `./install.sh` and require `./doctor.sh` to report `Result: ready` for `0.24.0`. - -| Boundary | Observable evidence | -| --- | --- | -| B1: protection | API readback shows public visibility, PRs, strict required CI, conversations, administrator enforcement, and zero extra approvals | -| B2: CI timing | Complete workflow inventory excludes task pushes and draft events; actual readiness starts `toolkit-tests` | -| B3: review identity | Frozen local commit equals remote branch and PR head; clean hosted review applies to that head | -| B4: merge gates | All paginated checks and conversations are accounted for; checks pass, no changes are requested, and GitHub reports mergeability | -| B5: integration | Clean local main fast-forwards to origin/main, contains the squash result, and passes main CI | -| B6: release identity | Source version and checksums agree; unused `v0.24.0` resolves to integrated main; release is neither draft nor prerelease | -| B7: consumption | Reviewed-candidate installation and Doctor succeed | - -If a correction occurs, repeat the current-head gates through the canonical procedure. Do not manufacture a correction to test this path. Static configuration invokes the unchanged launcher; it adds no production path requiring semantic trace closure. - -## Plan history and recovery - - -Carry the original records and scoped supersessions reconciled in CPK-058. The reading checkpoint can be reused after complete source identity and hash verification. Publication and native-review contracts remain in force. The current request adds public repository setup and a release; it does not reopen the CPK-058 implementation. - -- [Original 1](../../.agent/plan-history/plan-summary.20260819T195712262086Z.manual-recovery.md) -- [Original 2](../../.agent/plan-history/plan-summary.20260819T211423672232Z.manual-recovery.md) -- [Original 3](../../.agent/plan-history/plan-summary.20260822T050100617085Z.fd7dfe4c94e461a1824112794d31e1372d316ccf79eed8a3937d2754c1157e40.md) -- [Original 4](../../.agent/plan-history/plan-summary.20260822T065923051937Z.4415ee79c8b0327ba824768113192b4f60662d355fb4931876ec995a214a5526.md) -- [Original 5](../../.agent/plan-history/plan-summary.20260823T052048899607Z.c539b46a7e5fa56092a382fef046fd00d4271c42c4fda8e0f0e2216ce94df122.md) -- [Original 6](../../.agent/plan-history/plan-summary.20260824T031427928859Z.f30d03e6b396d05f07f5ce7eebc8b8e8b81e2b1cfe8ebc739342a6e444ca6968.md) -- [Original 7](../../.agent/plan-history/plan-summary.20260824T135017227348Z.7cfbec79d5ce39f1a1d436a31dccfe0669c616f252b6793d4b90dc2b34ad13d6.md) -- [Original 8](../../.agent/plan-history/plan-summary.20260824T164719361941Z.f1479c9effab9071b8ccaa86dce1dbee407b79647c6bb7d542aea8c75caae32b.md) -- [Original 9](../../.agent/plan-history/plan-summary.20260825T002758364682Z.4eba52594f2ef5bdbe93f4f0ead7b61802e894668d23c749b5af459f65a19437.md) -- [Original 10](../../.agent/plan-history/plan-summary.20260825T002911279202Z.940432714b78524077326cf1dea7571142fa6038e878a2fb7e884024bc8775a8.md) -- [Original 11](../../.agent/plan-history/plan-summary.20260825T172626414955Z.9eaf7888a286b18f69d5a94869ee99522214d23dd715a553664a2041108fced3.md) -- [Original 12](../../.agent/plan-history/plan-summary.20260825T173129857080Z.a3ee26a1802fb85c5a0a100ccb3c33c1a6fff358bd20b65636adc61f8d0de377.md) -- [Original 13](../../.agent/plan-history/plan-summary.20260825T183857932150Z.47ec1ac118b8c6c23f961b4099708aacc7031581a744bc389e6795e1c2007796.md) -- [Original 14](../../.agent/plan-history/plan-summary.20260901T024803899174Z.f5becdd56d889aba50bf375a29ab0feb9012128e404e73e7a664e0243eb5ab8f.md) -- [Original 15](../../.agent/plan-history/plan-summary.20260906T145108959420Z.4ca59f1efb35d2fec6091bc88b5848bb2e50226576f0a493f9ec85ed1838c57b.md) -- [Original 16](../../.agent/plan-history/plan-summary.20260906T161604059175Z.811836c214ecc89cb39c692f4366e4e79e56a698bf0d01445feb86fcd2c725f4.md) -- [Original 17](../../.agent/plan-history/plan-summary.20260906T184718818166Z.101806a6188b911af737dd47187082418727ed7042831dd332d77360d1cb6b93.md) -- [Original 18](../../.agent/plan-history/plan-summary.20260907T162300226611Z.ddc507f2e3b9b24182cb6abc4eb4782feae98a0c25f8cdc174a2bf8c2c9932a1.md) - - -Record operational evidence in `.agent/test-results/cpk-059-public-pr-release.md`. Preserve existing remote state after an actual failure. Never move or recreate a published tag. A missing hosted review connection requires configuration before readiness. Do not bypass protected main or discard local changes. - -Revision: define native CI, protection, and versioned release in response to the user's publication request and selected solo review gate. diff --git a/docs/plans/cpk-060-windows-codex-resolution.md b/docs/plans/cpk-060-windows-codex-resolution.md deleted file mode 100644 index b191a0a..0000000 --- a/docs/plans/cpk-060-windows-codex-resolution.md +++ /dev/null @@ -1,40 +0,0 @@ -# Resolve the Codex command on Windows - -This ExecPlan records the scope and validation for CPK-060. Maintain it according to `.agent/PLANS.md` until review closure. - -## Purpose - -The Windows installer and Doctor must run the npm-installed Codex command. Python cannot start the extensionless `codex` name directly when only the Windows npm command shim is available. - -## Scope - -Resolve `codex` with the Python standard library on Windows and reuse that path for plugin installation and Doctor checks. Keep the existing command name on macOS and Linux. Isolate Git test fixtures from the host's line-ending conversion so the Windows suite verifies repository bytes consistently. - -This bug fix publishes version `0.24.1`. It adds no dependency, configuration option, or new installation path. - -## Progress - -- [x] Reproduced the Windows command lookup failure. -- [x] Added one shared Windows command resolver and its regression check. -- [x] Isolated Git fixtures from global `core.autocrlf` settings. -- [x] Passed the complete test suite, installer, and Doctor on Windows. -- [x] Completed adversarial review. Publication continues through the protected pull-request workflow. - -## Plan history reconciliation - -No Plan Mode record applies to CPK-060. The task began from the user's direct bug report and publication request. - -## Validation and acceptance - -Run from the repository root: - - pwsh -File .\run-tests.ps1 - pwsh -File .\install.ps1 - pwsh -File .\doctor.ps1 - git diff --check - -Require every manifest checksum to match. Require Doctor to report `Result: ready` for toolkit version `0.24.1` and the installed Codex CLI. - -## Outcome - -On Windows, the toolkit uses the executable path returned by `shutil.which("codex")`. Native plugin installation and Doctor use the resolved npm `.CMD` shim. Other platforms keep the existing `codex` command. Final adversarial review found no actionable defect. diff --git a/docs/plans/cpk-061-component-updates-agent-cleanup.md b/docs/plans/cpk-061-component-updates-agent-cleanup.md deleted file mode 100644 index cefbfa3..0000000 --- a/docs/plans/cpk-061-component-updates-agent-cleanup.md +++ /dev/null @@ -1,148 +0,0 @@ -# Report managed component updates and clean finished agent threads - -This ExecPlan is a living specification until review closure. Maintain it in accordance with [`.agent/PLANS.md`](../../.agent/PLANS.md). - -## Purpose / Big Picture - -Users can run `python3 kit.py check-updates` to compare each managed component with its authoritative upstream source. The command reports availability and does not update files, installations, plugins, or configuration. - -Codex coordinators also receive precise cleanup instructions. They preserve required follow-ups, capture each terminal delegated result, close that exact agent thread, and archive only finished history subtrees. - -## Decision Log - -- Decision: Add an explicit `check-updates` command instead of a startup, install, or Doctor check. - Rationale: Network availability must not change deterministic setup and health operations. -- Decision: Treat `upstream.lock.json` sections `runtime_tools` and `skills` as the complete managed inventory. - Rationale: The same lock owns toolkit pins and bundled skill revisions. Its `optional_tools` section is explicitly outside the installed kit. -- Decision: Compare authoritative identities without version ordering. - Rationale: Equality can show that upstream differs. It cannot prove compatibility, safety, or that a release is chronologically newer. -- Decision: Use PyPI project JSON for RepoWise, GitHub latest full releases for uv and Ponytail, and GitHub default-branch heads for bundled skills. - Rationale: These endpoints match each component's pinned identity type. -- Decision: Buffer every result before output and stop after the first request error. - Rationale: A failed scan must not print a partial report that looks complete. The command does not retry. -- Decision: Native agent closure releases an open-thread slot. Native archival is a separate history operation. - Rationale: Archival is not proof that Codex released agent capacity. -- Decision: No Plan History record applies to CPK-061. - Rationale: Existing records describe earlier tasks. No prior Plan Mode specification defines this outcome. -- Decision: Use branch `cpk-061-component-updates-agent-cleanup` from `main` commit `00f3af7e9e91fdb7ddd31c529863c616522cdd82` in the primary checkout. - Rationale: This task has one writable implementation stream. - -## Context and Orientation - -`kit.py` is the Python command-line entry point. `build_parser` defines commands, `main` dispatches them, and `load_lock` reads `upstream.lock.json`. - -`upstream.lock.json` contains three managed runtime tools. RepoWise and uv have version pins. Ponytail is a Codex-owned plugin without a toolkit pin. The lock also contains two bundled skills with exact commit pins. - -`assets/skills/delivery-lifecycle/references/coordination.md` is the only live owner of coordinator and subagent lifecycle rules. Do not copy these rules into another live instruction file. - -`tests/test_kit.py` contains CLI and rule-owner integration tests. `README.md` owns the public command and component lifecycle documentation. `MANIFEST.sha256` records tracked package content. - -## Product Boundary - -The accepted user request, `upstream.lock.json`, and the canonical coordination reference define this task. Apply [Scope boundaries](../../assets/skills/design-preflight/references/scope-boundaries.md). - -The managed lock inventory, the `kit.py` CLI, canonical coordination instructions, Design Preflight follow-up rules, and README compose the result. Existing install, Doctor, plugin lifecycle, native thread lifecycle, and Codex thread-limit behavior remain opaque. Optional tools, automatic updates, persistence, retries, and thread-limit changes remain deferred. - -No inherited specification conflict exists. Do not alter component pins or installation behavior. Do not add background work, caches, schedules, dependencies, provider abstractions, version-order logic, or direct Codex state-file operations. - -## Supported Operating Model - -The supported path is an explicit online query against the five current managed components. A complete query returns status 0. The first network or response-shape error uses the existing `ERROR: ...` path and returns status 2. - -The command reports toolkit pins and upstream identities. It does not inspect installed versions. For Ponytail, it reports the latest upstream release and Codex ownership without a current or update-needed claim. - -A delegated assignment is terminal only when no required follow-up remains. After the coordinator captures that result, it closes the exact agent through the exposed native close operation before it spends another slot. If native archival is exposed, the coordinator explicitly targets a finished subtree with no active or required descendant. - -## Boundary Inventory - -| Boundary | Condition and contrast | Required oracle | Entry point | Scenarios | -| --- | --- | --- | --- | --- | -| B1 | Process all managed runtime tools and skills. Do not stop early, merge equal values, or include optional tools. | Five named results appear exactly once. No optional request or output occurs. | `kit.main(["check-updates"])` | S1 | -| B2 | The command performs reads and GET requests only. It does not mutate toolkit or Codex state. | Source, installation, plugin, and configuration state remain unchanged. | `kit.main(["check-updates"])` | S1, S5 | -| B3 | Compare version pins with releases and commit pins with repository heads. Do not fabricate a Ponytail baseline. | Each line uses the correct identity and same/different wording. Ponytail has Codex-owned wording only. | `kit.main(["check-updates"])` | S2, S3, S4 | -| B4 | A complete report returns 0. The first failed request returns 2 without retry, later requests, or partial success output. | Status, output, error count, and request sequence match the selected path. | `build_parser`, `main` | S1, S5, S6 | -| B5 | Capture a terminal assignment result, then close its exact agent. Archival is separate from capacity release. | The canonical rule states the actor, order, exact target, capacity purpose, and archive distinction. | Canonical coordination rule | S7 | -| B6 | Cleanup targets only finished work and preserves active or required descendants. | The rule requires an explicit archive target and forbids coordinator defaults and direct session deletion. | Canonical coordination rule | S8 | -| B7 | A finished turn is not a finished assignment when a required follow-up remains. | The same Design Preflight challenger survives both phases and becomes eligible only after Phase 2. | Coordination and Design Preflight rules | S9 | - -## Scenario Proof - -Apply [Scenario discrimination](../../assets/skills/design-preflight/references/scenario-discrimination.md), [Owner composition](../../assets/skills/design-preflight/references/owner-composition.md), and [Full-set results](../../assets/skills/design-preflight/references/full-set-results.md). - -| Scenario | Discriminator and contrast | Production path | Required oracle | Runnable check | -| --- | --- | --- | --- | --- | -| S1 | Use equal early identities and a different final skill revision. This exposes early stop and value deduplication. | `main` to parser, lock selection, provider parsing, comparison, and output | Exactly five managed results, no optional request, status 0, unchanged files | `python3 -m unittest discover -s tests -p test_kit.py -k test_check_updates_reports_complete_managed_inventory` | -| S2 | Vary RepoWise and uv between equal and different versions. Prefix uv tags with `v`. | `main` through real version comparison | Correct toolkit-pin and upstream-release labels, with no installed-version claim | `python3 -m unittest discover -s tests -p test_kit.py -k test_check_updates_compares_version_pins` | -| S3 | Vary each skill head between its exact pin and a different full SHA. | `main` through default-branch head requests and SHA comparison | Correct full revisions and same/different identity | `python3 -m unittest discover -s tests -p test_kit.py -k test_check_updates_compares_skill_revisions` | -| S4 | Give unpinned Ponytail the same release shape used by uv. | `main` through unpinned rendering | Upstream release and Codex-owned wording, with no installed/current/update-needed claim | `python3 -m unittest discover -s tests -p test_kit.py -k test_check_updates_reports_codex_owned_ponytail` | -| S5 | Change one later request from success to error after earlier requests complete. | `main` through the external seam and existing error owner | One error, status 2, no retry or later request, no stdout report, unchanged files | `python3 -m unittest discover -s tests -p test_kit.py -k test_check_updates_stops_once_on_request_error` | -| S6 | Select top-level help or subcommand help instead of command execution. | Parser help path | The read-only command is discoverable and makes no provider request | `python3 -m unittest discover -s tests -p test_kit.py -k test_update_check_is_explicit` | -| S7 | Compare final assignment cleanup with an idle but still-open thread or archive-only cleanup. | Canonical coordination instructions | Capture occurs before exact native closure and before another spawn. Archival is separate. | `python3 -m unittest discover -s tests -p test_kit.py -k test_coordination_cleans_terminal_agent_threads` | -| S8 | Keep a finished parent fixed and vary its descendant between active and terminal. | Canonical coordination instructions | Explicit archive targeting waits for active or required descendants and never targets the coordinator by default | `python3 -m unittest discover -s tests -p test_kit.py -k test_coordination_archive_targets_preserve_active_work` | -| S9 | Compare a Phase 1 return with completion of the full two-phase assignment. | Design Preflight through canonical cleanup gate | The same challenger remains available for Phase 2 and is cleaned only after the final result | `python3 -m unittest discover -s tests -p test_kit.py -k test_coordination_cleanup_preserves_required_followups` | - -## Plan of Work - -### CPK-061-A: Report managed component updates - -Add the minimum standard-library implementation to `kit.py`. Reuse `load_lock`. Add one JSON GET helper, fixed provider URL selection for the current inventory, buffered result formatting, parser registration, and main dispatch. - -Add the S1 through S6 tests to `tests/test_kit.py`. Replace only `urllib.request.urlopen` at the external boundary. Keep lock selection, comparison, formatting, parser dispatch, and error handling real. - -Document the command in `README.md`. This subtask changes `kit.py`, `tests/test_kit.py`, `README.md`, the ExecPlan, roadmap, and manifest. Its checkpoint review boundary is the complete update-reporting path. No separate checkpoint commit is required before the cumulative task review. - -### CPK-061-B: Clean finished delegated threads - -Edit only the canonical coordination owner for live instructions. Define assignment completion, result capture, exact native closure, optional explicit archival, descendant protection, and the ban on direct session-file deletion. - -Add the S7 through S9 deterministic owner tests to `tests/test_kit.py`. Keep the Design Preflight same-challenger text unchanged. This subtask changes the canonical coordination reference, tests, the ExecPlan, roadmap, and manifest. Its checkpoint review boundary is the instruction contract and its rule-owner checks. No separate checkpoint commit is required before the cumulative task review. - -## Concrete Steps - -Work from `/home/mbeutler/Projects/codex-practical-kit` on branch `cpk-061-component-updates-agent-cleanup`. - -Use `apply_patch` for tracked edits. After implementation, run each Scenario Proof command. Then run: - - python3 -m unittest discover -s tests -p 'test_*.py' - python3 kit.py check-updates --help - python3 kit.py --help - -Regenerate `MANIFEST.sha256` with the repository's existing manifest procedure. Record command results in ignored `.agent/test-results/CPK-061.md`. - -## Validation and Acceptance - -The focused tests must prove both sides of each listed contrast. The complete suite must pass. Help output must describe `check-updates` as read-only and must not access the network. - -A live `python3 kit.py check-updates` run can use the current network. Its output must contain RepoWise, uv, Ponytail, NeuroArxiv, and Simple English. The command can report differing identities without failing. - -Before native correctness review, a fresh read-only trace reviewer must close executable boundaries B1 through B4. Deterministic source checks and native review cover instruction boundaries B5 through B7. After a clean final review, move CPK-061 from Active to Completed and apply review closure. - -## Idempotence and Recovery - -The update command is repeatable because it writes no state. A failed request stops the command. Run it again only after the external problem is corrected. - -All source edits are ordinary Git changes. Preserve unrelated untracked `.mcp.json`, `.repowise/`, and `.vscode/` content. - -## Artifacts and Notes - -The preflight found no contract gap. RepoWise indexed base commit `00f3af7e9e91` with `index_behind: false` before implementation. - -## Interfaces and Dependencies - -Use Python's existing `urllib.request` and `json` modules. Add no dependency. - -`check_updates() -> None` owns the full scan and successful report. A small JSON GET helper returns a decoded JSON value and raises `KitError` for transport, HTTP, JSON, or required-field errors. `main` returns 0 after `check_updates` completes and keeps the existing status-2 exception path. - -The public interface is: - - python3 kit.py check-updates - -The output uses one concise line per managed component. Each line names the toolkit baseline or Codex-owned state, the upstream identity, and whether comparable identities are the same or different. - -## Outcomes & Retrospective - -Users can compare all managed component pins with upstream identities through one read-only command. Coordinators now preserve required follow-ups and separate capacity-releasing closure from targeted history archival. - -The fixed provider paths kept the update report small and explicit. Native Codex lifecycle operations remained in the coordination owner instead of toolkit runtime code. - -Plan note: CPK-061 combines two user-requested outcomes under their existing owners. The runtime path remains read-only, and native Codex lifecycle behavior remains outside toolkit code. diff --git a/docs/plans/cpk-062-managed-update-application-12ui.md b/docs/plans/cpk-062-managed-update-application-12ui.md deleted file mode 100644 index 43e7847..0000000 --- a/docs/plans/cpk-062-managed-update-application-12ui.md +++ /dev/null @@ -1,196 +0,0 @@ -# Apply managed updates and add website-only 12UI - -This ExecPlan is a living specification until review closure. Maintain it in accordance with `.agent/PLANS.md`. - -## Purpose / Big Picture - -The toolkit can report upstream releases, but it cannot act on that report. After this change, a user can run a small Bash or PowerShell command to check updates or explicitly apply every managed update. Application updates the source lock and the selected installed toolkit, so the next check, install, and Doctor result agree. - -The toolkit also installs the official 12UI Codex plugin. The global toolkit router permits that skill only for website projects. The toolkit does not copy or modify the upstream 12UI skill. - -## Surprises & Discoveries - -- Observation: Codex CLI 0.160.0 has no general `plugin update` command. A named Git marketplace is refreshed with `codex plugin marketplace upgrade NAME`, which refreshes installed plugin caches and preserves enabled state. - Evidence: the CLI help and the native plugin implementation expose the named marketplace upgrade operation. -- Observation: a current source pin does not prove that the selected installation is current. - Evidence: an updated checkout can coexist with skills installed from an older checkout. -- Observation: the documented 12UI install route is an official Git marketplace, not a copied skill directory. - Evidence: `just-every/12ui-plugin` documents `marketplace add just-every/12ui-plugin` and `plugin add 12ui-design@12ui-plugin`. -- Observation: Codex lists the 12UI package as local because the marketplace repository is also the package root. - Evidence: the installed record keeps the official Git marketplace identity and reports a local package source. - -## Decision Log - -- Decision: preserve `check-updates` as a read-only operation and add a separate `apply-updates` operation. - Rationale: checking must remain safe and explicit, while applying is an intentional mutation. -- Decision: add `check-updates.sh`, `check-updates.ps1`, `apply-updates.sh`, and `apply-updates.ps1` as thin sibling-script launchers. - Rationale: the shell files only locate `kit.py`, select one fixed command, forward arguments, and return its status. -- Decision: use `upstream.lock.json` as the single source of runtime versions, installer identities, skill revisions, native plugin sources, and package files. - Rationale: duplicated editable constants can make checking, installation, and Doctor disagree. -- Decision: resolve each selected skill commit through its complete, non-truncated Git tree and install every blob under its declared package root plus its declared repository license. - Rationale: a short static file list can silently omit added, changed, or removed package files. -- Decision: apply an exact RepoWise version through the existing managed `uv tool install` owner. Download and verify both official uv installer bodies, then execute only the current platform body. - Rationale: each installed runtime must match the selected lock identity and the platform paths remain distinct. -- Decision: manage Ponytail and 12UI through exact native Git marketplace selectors. Install an absent managed plugin and refresh an installed plugin with `marketplace upgrade`. - Rationale: this is the upstream-native lifecycle and preserves user enablement and plugin data. -- Decision: validate the 12UI local package through its official Git marketplace record. - Rationale: Codex resolves that local package from the verified marketplace snapshot. -- Decision: put the website-only 12UI restriction in the global routing owner, `assets/AGENTS.block.md`. - Rationale: the router owns activation scope. The upstream plugin continues to own its workflow. -- Decision: validate all candidates before the first mutation. Stop on the first operation failure without retry or a false completion message. - Rationale: this minimizes partial work while preserving the repository's accepted non-transactional model. -- Decision: evaluate checkout identity and tracked target modifications relative to `kit.py`'s `ROOT`, not the caller's current directory. - Rationale: an absolute launcher path must work from another directory. -- Decision: write the source lock only after the selected installation succeeds. - Rationale: a failed installation remains retryable, and the installed lock identifies a prior successful source write. -- Decision: no Plan History record applies to this task. The branch `cpk-062-managed-update-application-12ui` is based on reviewed CPK-061 commit `37a3bc69fc1ff09e6fc372320bafd29d4d867e2f`. - Rationale: the user continued from that local reviewed result and did not request publication. - -## Outcomes & Retrospective - -Users can now check or apply all managed updates through short Bash or PowerShell commands. Apply validates complete candidates, updates the source lock, and reconciles the selected installation even when the source identities already match. - -The toolkit installs or refreshes official Ponytail and 12UI plugins through their exact native marketplaces. The installed router limits 12UI to website projects. The update model remains explicit and non-transactional: it stops after the first error and can be run again after the user corrects the cause. - -The main design lesson is that source identity and installed state are separate facts. End-to-end checks must prove both through the real command and launcher paths. - -## Context and Orientation - -`kit.py` is the Python command owner. `check_updates` reads `upstream.lock.json`, queries official provider endpoints, and reports comparable identities. `install_core` stages locked skills, installs owned files, configures native plugins, writes the installed manifest, and installs global instructions. `doctor` checks the selected installation. - -`upstream.lock.json` is the authoritative managed inventory. `runtime_tools` contains RepoWise, uv, and native plugins. `skills` contains copied third-party skill packages. `optional_tools` is informative and is outside this task. - -`assets/AGENTS.block.md` is the live global router installed into the user's selected Codex home. `MANIFEST.sha256` lists distribution files. `tests/test_kit.py`, `tests/test_ponytail.py`, and the new focused update tests exercise installation and update behavior. - -## Product Boundary - -Follow [Scope boundaries](). The authoritative request is to apply reported managed updates, provide simpler Bash and PowerShell actions, add 12UI, and use 12UI only for website projects. - -The toolkit owns managed inventory selection, candidate validation, source-lock writes, installed toolkit files and records, exact native marketplace selection, global router text, launchers, Doctor checks, and terminal status. Official HTTP providers, installer internals, Codex plugin storage, and the internal Ponytail and 12UI workflows are opaque external owners. - -Normal use is one personal user and one writer, online official provider reads, a normal Git checkout, clean tracked update targets, and a selected installation whose manifest owns its targets. A managed plugin can be absent or installed from its official source. - -The hard ceiling excludes optional tools, background or scheduled updates, version-order policy, general package management, new dependencies, retry, rollback, recovery, permission or interruption models, arbitrary repository instruction overrides, plugin storage parsing, modified upstream skills, and claims about future model behavior. - -## Scenario Proof - -The accepted behavioral boundaries are: - -- B1: Check and apply cover each managed component exactly once, including 12UI. They exclude optional tools and unrelated plugins. -- B2: Check remains explicit and read-only. It reports comparable identities honestly and does not invent a baseline for native plugins. -- B3: Apply changes the selected managed installation. Runtime versions, complete skill files, verification identities, records, and affected Doctor results must agree. -- B4: Plugin refresh targets only the exact managed marketplaces in the selected Codex home. It preserves enablement, settings, unrelated marketplaces, and the default home. -- B5: Toolkit instructions permit 12UI only for website design. Installation and refresh must not add a contradictory broader toolkit instruction. -- B6: Ordinary installation adds an absent official 12UI plugin. It reuses an existing official disabled plugin without re-enabling it. -- B7: Each launcher resolves its sibling `kit.py`, preserves arguments and destinations, and returns the Python command status from another working directory. -- B8: The first operation error stops the action after one attempt. The command returns a failure status and prints no partial check report or false apply success. - -Follow [Scenario discrimination](), [Owner composition](.md", + "Update that file instead of creating timestamped revisions", + "Git commit and repository path", + "Compare every covered decision with its original", + "A SHA-256 match proves byte identity, not semantic fidelity", + "Do not build chains of summaries of summaries", + "Never discard a unique unresolved constraint", + "Status: superseded", + "Retain decisions outside that scope", + "Stop planning when retained decisions conflict", + "", + "Relocate applicable untracked Plan records", + "Do not overwrite", + "Compare complete source and destination bytes", + "If they differ or the copy fails, preserve both and stop", + ): + self.assertIn(clause, skill) + for obsolete in ("Never overwrite a summary revision", "retain their last copies", + "Never edit a Plan history record or remove its last copy", + "Link every applicable original record"): + self.assertNotIn(obsolete, skill) self.assertIn("plan-history", kit.CUSTOM_SKILLS) - self.assertIn("cpk-rule-owner: plan-history", skill) - self.assertIn("Inventory every original record in `.agent/plan-history/`", skill) - self.assertIn("before the next submitted prompt continues", skill) - self.assertIn("Every repository Plan capture has a record", skill) - self.assertIn("Do not trust a RepoWise match limit", skill) - self.assertNotIn("If the complete applicable set cannot fit in context, stop", skill) - self.assertIn("including chunks within one large record", skill) - self.assertIn("Every applicable original must have complete direct-read coverage or verified summary coverage", skill) - self.assertIn("enumerate the original inventory again", skill) - self.assertIn("do not emit a plan based on an unread tail", skill) - self.assertIn("compacted/..md", skill) - self.assertIn("these derived summaries are not original captures", skill) - self.assertIn("A broader task must reopen the original evidence", skill) - self.assertIn("A SHA-256 match proves byte identity, not semantic fidelity", skill) - self.assertIn("Do not build chains of summaries of summaries", skill) - self.assertIn("new, uncovered, changed, or distinct-content records", skill) - self.assertIn("Original evidence takes precedence", skill) - self.assertIn("retain carried decisions outside that scope", skill) - self.assertIn("both original sources", skill) - self.assertIn("not summary creation times", skill) - self.assertIn("before long reads and after each completed chunk or batch", skill) - self.assertIn("Do not mark that record complete", skill) - self.assertIn("continue from the first unaccounted range", skill) - self.assertIn("reconstruct coverage from verified reusable summaries", skill) - self.assertIn("reread that source from its beginning", skill) - self.assertIn("Summary links are supplemental", skill) - self.assertIn("same event key and identical bytes", skill) - self.assertIn("Retain and reconcile every distinct-content collision record", skill) - self.assertIn("duplicate", skill.lower()) - self.assertIn("Prior plan reconciliation", skill) - self.assertIn("Status: superseded", skill) - self.assertIn("", skill) - self.assertIn("implements a plan after context was cleared", skill) - self.assertIn("specification becomes known after capture", skill) - self.assertIn( - "enumerate every other worktree in the same Git repository before task edits", - skill, - ) - self.assertIn("Exclude the task worktree", skill) - self.assertIn( - "Relocate each applicable untracked record to the same repository-relative path", - skill, - ) - self.assertIn("Inspect the task-worktree destination before writing", skill) - self.assertIn("Do not overwrite an existing destination", skill) - self.assertLess( - skill.index("Compare the source and destination bytes"), - skill.index("remove the redundant untracked source copy"), - ) - self.assertIn("If the bytes differ or the destination copy fails", skill) - self.assertIn("During worktree handoff, never remove a tracked, unique, unrelated, or different-content record", skill) - self.assertIn("Retain every distinct-content collision record", skill) - self.assertIn("This is the only location for new repository summaries", skill) - self.assertIn("Keep these records versioned in Git", skill) - self.assertIn("git worktree list --porcelain -z", skill) - self.assertIn("also read legacy siblings", skill) - self.assertIn("link the existing central record", skill) - self.assertIn("Do not copy it back to `main`", skill) - self.assertIn("Compare the complete source and destination bytes before removing the legacy copy", skill) - self.assertNotIn("also create exact sibling records", skill) - self.assertNotIn("copy the exact unlinked record beside it", skill) - self.assertIn("Never edit a Plan history record or remove its last copy", skill) - self.assertNotIn( - "copy each applicable untracked record to the same repository-relative path before task edits", - skill, - ) - self.assertIn("`plan-history`", agents) - self.assertIn("Immutable Plan Mode summaries are source records", plans) - self.assertIn("cpk-rule-route-only: plan-history", isolation) + + def test_lifecycle_removes_spent_artifacts_without_archives(self): + delivery = (ROOT / "assets/skills/delivery-lifecycle/references/delivery-lifecycle.md").read_text() + plans = (ROOT / ".agent/PLANS.md").read_text() + for clause in ( + "Git owns historical versions. Do not create duplicate archives.", + "at task start, before planning or replanning, and at delivery", + "Delete task-owned temporary files immediately after their last required use", + "Remove the active result record when the authorized task sequence finishes", + "If a required follow-up remains, retain only the evidence that it needs", + "Retain only output for active work or explicitly approved releases", + "Remove superseded candidates and obsolete output", + "Preserve active work, unrelated user files and configuration, and unknown ownership", + "Ignored or untracked status alone is not permission to delete", + "Do not use blanket `git clean`", + ): + self.assertIn(clause, delivery) + self.assertIn("pending integration", plans) + self.assertNotIn("Do not rewrite completed ExecPlans", plans) + self.assertNotIn("Immutable Plan Mode summaries", plans) def test_repowise_is_required(self): config = kit.repowise_config_block(