V3 Issue #245 — Strategic Plans Implementation Plan

For agentic workers: execute this indexed plan task by task; keep the PR based on #242 and do not merge it.

Goal: Preserve Plan Mode as a non-executing, versioned user approval of stable objectives, acceptance criteria, workspace scope, permitted effects/capabilities, and risk limits, with a linked mutable Working Plan.

Architecture: Extend the existing InteractionController event-sourced proposal lifecycle and TaskManager transaction. Keep proposals and legacy message shapes as compatibility projections; persist the accepted Strategic Plan and linked Working Plan/tasks in the existing event and task stores, atomically. Strategic acceptance remains separate from capability grants, tool approvals, task evidence, and completion.

Tech Stack: Python 3.12–3.13, unittest, existing SQLite repositories and interaction event log; no new dependency.

Spec: GitHub issue #245, requirements R069–R073, R077, and R080; approved batch plan in the task history.

Global Constraints

Plan Mode must not execute a proposal.
Approval covers objectives, acceptance criteria, workspace paths, effect/capability categories, and the existing normal/high risk ceiling.
Working Plan edits may adapt execution but cannot redefine approved intent.
Plan approval never grants capabilities or replaces tool approval.
Acceptance and its linked Working Plan/tasks/events commit atomically; duplicate acceptance is idempotent and stale versions fail without task creation.
Preserve existing proposal/message shapes through explicit compatibility defaults; missing legacy bounds never widen scope automatically.
No new dependency, paid provider call, or unrelated V3 work.

Files in Scope

openkyrozen/agent/modes.py: proposal validation, Strategic Plan version/fingerprint, controller state/acceptance, and user-facing rendering.
openkyrozen/agent/prompts.py, openkyrozen/agent/protocol.py, openkyrozen/agent/loop.py: proposal contract, bounded defaults, acceptance and terminal lifecycle integration.
openkyrozen/tasks/engine.py, openkyrozen/tasks/ports.py, openkyrozen/persistence/tasks.py, openkyrozen/persistence/store.py, and SQLite migration code: atomic creation of the linked Working Plan and event records, with per-task objective/criterion references.
tests/test_interaction.py, tests/test_working_plans.py, tests/test_sqlite_migrations.py: contract, compatibility, lifecycle, and durability regressions.
docs/tasks-and-automation.md, docs/superpowers/plans/index.md: user-facing contract and this indexed plan.

Review Focus

A stale or duplicate acceptance must never create duplicate tasks or accept a different version.
A legacy proposal without bounds must not imply workspace or authority expansion.
Revisions must keep stable objective/criterion identifiers where meaning is unchanged and create new identities when meaning changes.
Failed persistence must leave both interaction state and Working Plan state unchanged.
Completion and cancellation must remain distinct; cancellation cannot emit successful Strategic Plan completion.

Task 1: Versioned Strategic Plan contract

Files: openkyrozen/agent/modes.py, openkyrozen/agent/prompts.py, tests/test_interaction.py.

[ ] Add failing tests for normalized bounds, duplicate objective/criterion identifiers, stable fingerprints, version increments, legacy proposals without bounds, and safe normal-risk/workspace defaults.
[ ] Extend validate_plan_proposal() with objectives/step identity, stable acceptance criterion IDs, bounds, and a canonical fingerprint while preserving current title, summary, assumptions, steps, and original_input fields.
[ ] Normalize legacy string criteria deterministically; preserve IDs across unchanged revisions and generate new criterion IDs when criterion meaning changes.
[ ] Define compatibility defaults as the current workspace (.), read-only effect/capability, and normal risk; explicit proposal bounds may request more, but only the displayed user acceptance approves them.
[ ] Update Plan Mode prompt examples and render_plan() to show objectives, criteria IDs, workspace paths, effects/capabilities, risk ceiling, version, and fingerprint.
[ ] Run the focused proposal and rendering tests on Python 3.12 and 3.13.

Task 2: Atomic acceptance and task linkage

Files: openkyrozen/agent/modes.py, openkyrozen/tasks/engine.py, openkyrozen/tasks/ports.py, openkyrozen/persistence/store.py, openkyrozen/persistence/tasks.py, migration code, tests/test_interaction.py, tests/test_working_plans.py, tests/test_sqlite_migrations.py.

[ ] Add failing tests for exact-version acceptance, duplicate acceptance, stale acceptance, and transaction rollback without partial plan/task/event state.
[ ] Extend the existing Working Plan edit transaction to append the correlated interaction.plan_accepted event in the same SQLite transaction.
[ ] Replace per-task add_ordered_plan() acceptance with one revision-zero Working Plan edit; attach Strategic Plan ID/version, objective ID, and acceptance criterion IDs to each task using existing checkpoint metadata.
[ ] Persist a strategic binding on the Working Plan using the minimal SQLite field(s) needed for durable recovery; keep prior migration data intact.
[ ] Reconstruct accepted and executing Strategic Plan state only from persisted proposal/acceptance events and the linked active Working Plan. Do not recreate tasks on restore.
[ ] Run interaction, plan, and migration tests on Python 3.12 and 3.13.

Task 3: Lifecycle, interfaces, and compatibility

Files: openkyrozen/agent/modes.py, openkyrozen/agent/loop.py, openkyrozen/agent/protocol.py, openkyrozen/agent/session.py, relevant interface projections, tests/test_interaction.py, tests/test_web_sessions.py, docs/tasks-and-automation.md.

[ ] Add failing tests for non-executing Plan Mode, linked task bounds, post-restart state, separate tool authorization, successful completion, and cancellation without false completion.
[ ] Keep working-task adaptation tied to approved objective and acceptance IDs; do not allow acceptance to change workspace or execution authority.
[ ] Emit one versioned definitive completion event only after existing evidence gates complete the linked Working Plan; terminal failure/cancellation must retain its actual status.
[ ] Preserve legacy proposal payloads and direct callers through bounded compatibility adapters; ensure an unbounded historical proposal is marked legacy and cannot silently authorize scope expansion.
[ ] Update docs to distinguish Strategic Plan approval, mutable Working Plan changes, and tool approvals.
[ ] Run focused interface/session acceptance on Python 3.12 and 3.13.

Task 4: Verification and delivery

[ ] Run all focused tests on Python 3.12 and 3.13; run full tests, make check, make lint, make docs-check, Go TUI tests, and offline agent/subagent/TUI acceptance.
[ ] Independently review the final diff, reproduce actionable Codex/CodeRabbit findings, publish fixes, and resolve applicable threads.
[ ] GPG-sign commits and verify signatures locally and on GitHub; run final-head CI, attach the PR, and leave #245 open and unmerged.

Validation Record

Implementation started from PR #284 head 0d49d4a488f6a9894b42900054cf06c665b9809f, based on refreshed main d71d2bd42b68485feb4571d3aad490d7d8327aa3.

PASS: focused contract, atomic acceptance, stale-version, version-increment, capability/effect/risk, workspace-path and symlink-scope tests on Python 3.12 and 3.13.
PASS: make check, make lint, and Python compile checks.
BLOCKED: make docs-check and the app-bootstrap portions of the full unittest suite import the installed Python 3.14 Pydantic binary through PYTHONPATH; this binary is unavailable to the local 3.12/3.13 interpreters. Full unittest run: 647 tests, 7 skipped, 11 failures and 259 errors, dominated by that import failure. CI on the supported runtimes is required to verify the complete suite.
PENDING: independent diff review, CI, signed commit verification, and PR publication.

Review follow-up

[x] Reproduced the runtime receipt path for a two-criterion objective. The first verified receipt previously succeeded the task, while a generic checkpoint action also shadowed later criteria with different actions.
[x] Strategic task receipts now preserve per-criterion matching and keep the task active until all bound acceptance IDs have verified evidence.
[x] Added a runtime receipt regression that processes the actual write and read receipts in sequence, confirms the task remains active after the first receipt, and succeeds after the second.
[x] Rechecked the subagent file-verification review findings against current subagent_runtime.py and its content-matching regression; both behaviors were already implemented in the base commit.
PASS: strategic plan acceptance suite, 10 tests, on Python 3.12 and 3.13.
BLOCKED: runtime application bootstrap tests remain blocked locally by missing Python 3.14 pydantic_core; no paid provider calls were used.
PASS: make lint and git diff --check after review fixes.
BLOCKED: make check passed Python architecture, syntax, inventory, and shell checks but the Go test exhausted the host's 117 MiB remaining disk. The Go cache was cleared; rerun is pending.
BLOCKED: make docs-check reaches the inventory generator but the installed Python 3.14 pydantic_core extension cannot load under Python 3.12.

Final-head review follow-up: PR #285

Before changing code, reproduce the eight outstanding findings on head befb08c and add regressions. Keep the scope within #245 and its Working Plan boundary; do not start #246 here.

Parse legacy JSON-object arguments before Strategic Plan path/effect checks, so serialized search_files and edit_file paths cannot bypass accepted roots.
Canonicalize legacy arguments once for ExecutionReceipt and acceptance matching, without changing the string passed to legacy executors.
Reject non-string risk_ceiling values with InteractionError rather than leaking TypeError from set membership.
Require Strategic Plan objective/criterion bindings for Working Plan additions or semantic updates while a plan is executing; preserve valid bindings for allowed ordering and dependency edits.
Permit the exact staged material revision to replace its previous executing revision through one transaction, retaining prior evidence and preventing simultaneous active plans.
Reconcile completion from durable terminal Working Plan state after restart so a crash between task terminalization and completion-event append cannot strand Agent mode.
Make concurrent duplicate acceptance idempotent inside the transaction by returning the already-linked plan for the same accepted version/fingerprint.
Reconstruct active accepted bounds independently of the capped generic event listing so long sessions cannot lose capability, effect, risk, or workspace checks.

All eight findings were reproduced and fixed; regressions cover each boundary. Also fixed two issues exposed while reproducing the findings: receipt evidence now preserves the Strategic Plan checkpoint, and normalized proposals retain their verification contracts on revalidation.

PASS: tests.test_interaction tests.test_working_plans tests.test_execution_receipts — 138 tests on Python 3.12 and 138 on Python 3.13.
PASS: make check, make lint, and make docs-check with the supported Python 3.12 environment and writable temporary Go/Python caches.
FAIL (pre-existing): full Python 3.12 suite — 735 tests, 2 failures, 146 errors. The strategic delegation test also fails on the original PR #285 head befb08c; one unrelated prompt-size test fails at 10,002 characters; most errors are SQLite access failures against protected host state. CI on the published head is still needed for full supported-runtime confirmation.
BLOCKED: browser-backed acceptance and full Python 3.13 suite were not run locally. The focused Python 3.13 suites passed; browser and full-suite coverage remain delegated to CI.
PASS: git diff --check; independent manual review found no additional actionable defects in the changed paths.

The update remains limited to #245. Leave PR #285 and issue #245 open and unmerged.

Stacked CI follow-up

CI on the first review-fix head exposed a stale workflow acceptance fixture that proposed mutating work without explicit capability/effect bounds or action verifiers. The Strategic Plan correctly denied those actions, exhausting the scripted response fixture.
The next CI run exposed that JSON-string structured edit_file arguments were not canonicalized before task-contract matching. The foreground scope check parsed them, but task matching fell through to the original spaced JSON string.
Canonicalized structured JSON arguments at the shared mutation-matching boundary and added an end-to-end regression. Updated the workflow fixture with explicit bounds and verifiers; it now asks the runtime to read the test harness and runs that generated test from the acceptance harness itself, avoiding an unapproved arbitrary process action.
The following CI run advanced through the structured edit and caught a stale TaskDone index in the fixture. Corrected the task sequence; the next run then showed that an edit receipt alone does not establish the file-content criterion, so the fixture now reads the edited file before completing that task.
Final CI for that head passed the wheel acceptance and reported two task-consistency errors plus the previously observed delegation failure. The task errors came from a mismatch between canonical receipt arguments and legacy task checkpoints: initial receipts did not reconcile, and duplicate-operation IDs differed between successful and rejected receipts.
The execution boundary now matches legacy checkpoint strings only for pending legacy tasks while preserving canonical fingerprints for structured contracts; duplicate detection and rejected receipts share the canonical operation identity. Both task-consistency regressions pass locally.
PASS: interaction, Working Plan, receipt, and task-consistency suites — 171 tests on Python 3.12 and 171 on Python 3.13. Workflow normalization, Strategic Plan validation, atomic acceptance, and every declared action contract also pass locally without network or provider calls.
PASS: make check, make lint, and make docs-check after the fixture and parser changes.
PENDING: rerun full dispatched CI on the updated final head. The local browser acceptance cannot bind localhost sockets in this sandbox.

Delegated legacy-action CI regression

[x] Reproduced test_delegated_receipts_do_not_infer_strategic_plan_task_association passing on the #242 base branch and failing on the current #245 head.
[x] Add an optional, user-visible structured write_file/edit_file contract to a Strategic Plan objective. Bind it into the plan fingerprint and linked task checkpoint; require exact action/arguments for delegated matching, without inferring or attaching a task ID to the child receipt.
[x] Recheck the parent Strategic Plan's capability, effect, risk, and workspace bounds before allowing delegated file operations.
[x] Rerun the focused regression and plan/delegation suites on Python 3.12; same-basename/different-directory writes remain blocked and the successful child receipt has no inferred task ID.
PASS: interaction, Working Plan, receipt, task-consistency, and delegation suites — 213 tests on Python 3.12; make check, make lint, and make docs-check pass.
BLOCKED: local Python 3.13 focused suite could not be provisioned because PyPI DNS/network access is unavailable; CI will provide supported-runtime validation.
[ ] Rerun final-head CI and obtain independent automated review before beginning #246.

Read-verifier evidence review finding

[x] Reproduced the finding by tracing read_file receipts with not_applicable verification into criterion-ID reconciliation: action/path equality alone credited arbitrary content claims.
[x] Require an explicit equals or contains predicate for Strategic Plan read_file verifiers, display and fingerprint it, and compare it with the actual returned text before recording criterion evidence.
[x] Add wrong-content and matching-content regressions, update existing read-verifier fixtures/docs, and rerun focused suites; final-head CI remains pending.
[x] Update the installed-runtime workflow acceptance fixture with read predicates; its loopback acceptance now passes locally.
[x] Tighten the shared predicate guidance after full CI caught compact-prompt length drift; both compact-size and Plan-mode prompt regressions pass locally.

Final-head Codex review findings

[x] The workflow-verifier predicate finding was already fixed in b8bc73f; the review was against its parent head, and loopback acceptance confirms the fixture now supplies both predicates.
[x] Exclude cancelled tasks from prior Strategic Plan revisions when validating completion; retain completion checks for every noncancelled member and require its current strategic binding.
[x] Verify read_file predicates against the private, full ToolResult.text, while keeping persisted evidence bounded and redacted; regressions cover content beyond the public projection limit and redacted projection text.
[x] Require exact checkpoint matching whenever a task has an explicit execution contract; retain bounded path-based mutation support only for tasks without an exact contract.
[x] Apply parent Strategic Plan capability/effect/path bounds to every delegated action, including reads; retain task matching for mutations.
[x] Reject Strategic Plan acceptance while an unrelated active Working Plan exists, preserving that plan and its tasks.
[x] Derive new proposal versions from the latest historical proposal for the executing plan, including cancelled revisions, so stale approval identifiers cannot target a replacement.
[ ] Run final focused/full CI, refresh automated review, and resolve all remaining review threads before continuing to #246.

Follow-up review fixes: pathless reads now authorize their effective . path; explicit file objectives match only that exact file; cancelled current objectives remain completion blockers; contract actions are checked against normalized bounds; verifier receipts may match separately from execution actions; and every required acceptance ID is enforced. Focused interaction and execution-receipt suites pass. GitHub lists piggyevan123@gmail.com as the verified address for the signing key; this follow-up uses that identity.

Local full-suite status: 879 of 880 tests passed; the remaining existing 50 ms provider transport-timeout test also fails unchanged on main (146bb19) because no request reaches the fixture before the deadline. The final-head CI workflow dispatch is running; review fixes themselves pass their focused suites.