feat(planning): converge trycycle refinement and harden gating - #723
Open
shaug wants to merge 25 commits into
Open
feat(planning): converge trycycle refinement and harden gating#723shaug wants to merge 25 commits into
shaug wants to merge 25 commits into
Conversation
- add a complete implementation plan for converging Atelier planning with trycycle mechanics and prose - define refinement contracts, invariants, file-level decomposition, and task-by-task execution/test strategy - lock user decisions on opt-in refinement, viral lineage, approval gates, and default round budgets
- Replace the plan with a fail-closed, executable architecture that separates baseline planning doctrine from iterative refinement mechanics. - Add explicit any-time refinement activation, approval-evidence, lineage propagation, and canonical verdict contracts. - Strengthen convergence quality gates with source-backed trycycle doctrine/mechanics mapping and coverage-driven test additions.
- add a prioritized, user-visible test plan for trycycle refinement convergence - define required harnesses and dependency ordering before test implementation - cover refinement activation, lineage propagation, claim gating, doctrine parity, and differential checks against trycycle references - document explicit exclusions and residual risks in a coverage summary
- Add a source-backed mapping of trycycle doctrine and iterative mechanics. - Document Atelier adaptation boundaries and non-goals. - Add regression tests and local trycycle reference fixtures for convergence drift.
- Introduce a reusable planning doctrine skill from Atelier + trycycle guidance. - Route planner behavior through the doctrine skill instead of template-only prose. - Add contract tests to prevent doctrine drift.
- Add typed refinement artifact parsing and gate-evaluation helpers. - Add project/user policy defaults with trycycle-aligned budgets. - Add tests for parsing, verdicts, and config validation.
- Add plan-set-refinement for explicit refinement activation on existing work. - Enforce approval evidence requirements for required refinement mode. - Update planner guidance and tests for activation routing.
- Add bounded stateless planning rounds with explicit verdict protocol. - Adapt trycycle prompt-builder mechanics with provenance comments. - Add convergence and non-convergence regression tests.
- Make create/split/promote/guardrail scripts refinement-aware. - Enforce lineage inheritance and approval/verdict readiness diagnostics. - Add script-level regression coverage for refinement flows.
- Reject refined work claims without approval evidence and READY verdict. - Keep unrefined claim behavior unchanged. - Add selection/template tests for lineage-aware overscope handling.
- Add plan-refined-deliberation alias to preserve older entry points. - Keep refine-plan as the canonical iterative refinement skill. - Extend packaging tests for new planning/refinement skills.
- Resolve full-suite regressions discovered during final gates. - Keep changes scoped to quality-gate fixes only.
- Require complete approval evidence for required refinement before claimability succeeds. - Base claim-gate requiredness on the selected winning record while preserving fail-closed handling for malformed required metadata. - Add project-policy resolution in plan-set-refinement, auto-record policy approval evidence, apply policy budgets by default, and add regression/performance tests.
- Make refine-plan runnable without simulation by using a fail-closed default round executor and terminal USER_DECISION_REQUIRED handling. - Add snapshot-backed differential checks for refine-plan loop anchors and expand script tests for default CLI behavior. - Make inherited refinement propagation atomic by embedding inherited notes in create mutations for plan-changesets and plan-split-tasks. - Gate epic-only promotion paths on refinement readiness and add regression tests for refined epic-without-children blocking. - Add unrefined control coverage for changeset inheritance behavior per the finalized test plan.
- Persist authoritative planning_refinement.v1 evidence from refine-plan runs back to issue notes, including rounds used, latest verdict, and artifact links. - Preserve existing refinement contract fields during persisted updates and require issue context for refine-plan execution. - Enforce ISO-8601 validation for approved_at timestamps in refinement records and add regression coverage in parser and set-refinement flows. - Accept tuple-backed notes in guardrail normalization so required refinement completeness checks cannot be skipped. - Expand refine-plan and guardrail tests with red/green coverage for note persistence, timestamp validation, and tuple-note contract evaluation.
- make the default refine-plan executor classify executable plans as READY instead of always hard-failing, while preserving fail-closed behavior for non-executable input - fix append-notes verification for multiline note blocks so refinement evidence persistence can be verified atomically - add H1 integration harness helpers and real store-backed integration coverage for set-refinement, changeset inheritance, split-tasks inheritance, and epic-only promote gating - add startup control coverage for malformed unrequired refinement metadata staying claimable on explicit epic startup paths - add store contract regression coverage for multiline note append behavior
- Wire refinement notes into epic claimability evaluation in beads, store adapter, and session runner classification paths so required non-READY refinements fail closed. - Replace non-simulated refine-plan execution with a runtime round executor that renders prompt-builder templates, invokes an external round runner, and parses structured verdict output. - Resolve refinement max-round budgets with precedence across CLI override, persisted refinement metadata, and project policy defaults. - Add TDD coverage for claim gate wiring, startup missing-approval rejection, runtime refine-plan execution path, and round-budget resolution behavior. - Refresh beads facade inventory counts and format touched plan docs.
- Treat blocks as contiguous field records and stop parsing at freeform note text, preventing unrelated appended notes from invalidating valid refinement evidence. - Restrict recognized field lines to contract-style keys so prose with colons is not misparsed as refinement metadata. - Make non-simulated fail closed with when no round runner is configured, removing checklist-shape auto-READY behavior. - Add TDD coverage for trailing freeform-note parser isolation and no-runner fail-closed behavior on executable-looking plans.
- Fail closed in plan-changesets when fallback parent-note lookup errors, so refined lineage cannot be silently dropped under lookup failures. - Keep direct store notes as the primary source and only use fallback lookup when notes are unavailable on the parent record. - Reject operator approval_source for required project_policy mode and require project_policy attribution for policy-derived approvals. - Add TDD coverage for parent-note lookup failure handling and project_policy approval-source validation. - Update planner store migration contract parity test wiring so fallback note reads use the test backend client.
- Enforce strict newest-authoritative selection semantics in planning refinement so malformed newest authoritative blocks fail closed instead of falling back to older valid records. - Add shared refinement invariant helpers for policy resolution, approval validation, and round budget precedence. - Move required-refinement validation ahead of epic creation mutation and apply resolved policy/override budgets in plan-create-epic. - Apply shared invariant handling in plan-set-refinement and resolve policy defaults for requested mode budgets. - Add regression tests for malformed newest-authoritative fail-closed behavior, create-epic pre-mutation validation, and policy default budget propagation.
- tighten refinement block parsing to only accept recognized keys so trailing ordinary key/value notes do not invalidate valid authoritative records - make refine-plan resolve existing notes through the real show-path fallback when store models omit notes, preserving required/approval evidence during persisted updates - fail closed in plan-changesets when parent notes indicate required refinement but the winning record is malformed - add focused red-to-green tests for parser isolation, refine-plan note fallback, and malformed-required lineage rejection
- mirror create-changeset fail-closed lineage behavior in split-tasks when required parent refinement metadata is malformed or unusable - resolve effective refinement round budgets once per run and persist those effective values in refinement evidence after precedence resolution - keep compatibility helpers for existing max-round tests while routing runtime persistence through effective budget resolution - add focused regression tests for malformed required split lineage rejection and persisted effective budget correctness under CLI override
- apply child refinement gating only to executable promotion-path children by excluding closed lifecycle records - keep existing refinement blocking behavior for deferred/open/in-progress/blocked children unchanged - add regression coverage proving closed children with non-ready refinement metadata do not block epic promotion
- enforce epic-level refinement readiness in plan-promote-epic even when child changesets exist, while keeping closed-child skip and existing child gating behavior intact - make planning_refinement block parsing fail closed on unknown/malformed in-block lines instead of truncating and validating partial defaults - preserve append-only note behavior by treating blank lines as refinement block boundaries so trailing freeform/key-value notes are not absorbed - add regression coverage for epic-with-children gating, malformed unknown-field fail-closed parsing, and permutation-based winner-selection determinism
…ness - treat non-key freeform lines after a refinement block as block boundaries so single-newline note appends do not invalidate otherwise valid required refinement metadata - keep fail-closed behavior for unknown key:value lines inside refinement blocks to prevent silent malformed-field truncation - stop propagating parent latest_verdict into inherited child refinement notes in both changeset creation flows so descendants cannot inherit READY state - add regression coverage for single-newline append parsing and for inherited-note payloads excluding latest_verdict
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
planning_refinement.v1block.key: valuelines inside refinement blocks.latest_verdictwhen creating inherited refinement notes in both:plan-changesetsplan-split-taskslatest_verdict.Test Plan
uv run pytest tests/atelier/test_planning_refinement.py tests/atelier/skills/test_plan_changesets_script.py tests/atelier/skills/test_plan_split_tasks_script.py -k "ignores_single_newline_appended_freeform_note or inherits_required_refinement_from_parent or propagates_inherited_refinement_from_parent" -vuv run pytest tests/atelier/test_planning_refinement.py tests/atelier/skills/test_plan_changesets_script.py tests/atelier/skills/test_plan_split_tasks_script.py -k "ignores_single_newline_appended_freeform_note or fails_closed_on_unknown_field_inside_block or inherits_required_refinement_from_parent or propagates_inherited_refinement_from_parent" -vuv run pytest tests/atelier/test_planning_refinement.py tests/atelier/skills/test_plan_changesets_script.py tests/atelier/skills/test_plan_split_tasks_script.py tests/atelier/skills/test_plan_promote_epic_script.py -vjust format→ passedjust lint→ passedjust test→ passed (1749 passed+ shell suites passed)