diff --git a/planfile/__init__.py b/planfile/__init__.py index d532740c..56156104 100644 --- a/planfile/__init__.py +++ b/planfile/__init__.py @@ -585,7 +585,8 @@ def block_ticket(self, ticket_id: str, reason: str | None = None, note: str | No already started, that leaves ``execution.state="running"`` behind, which watchdogs read as an active but idle claim. Blocking is a lifecycle transition, so it must clear the running execution state too. - The `reason` here is the block reason (used for description + history "reason"). + The `reason` is retained in history. A synthetic description is only used + when the ticket has no accepted description to preserve. `actor` records who performed the block. """ ticket = self.get_ticket(ticket_id) @@ -601,7 +602,8 @@ def block_ticket(self, ticket_id: str, reason: str | None = None, note: str | No }) updates: dict = {"status": "blocked", "execution": TicketExecution(**data)} if reason: - updates["description"] = f"BLOCKED: {reason}" + if not ticket.description: + updates["description"] = f"BLOCKED: {reason}" updates["reason"] = reason # for history if note: updates["outputs"] = self._append_note(ticket, note) diff --git a/project/ticket-282/README.md b/project/ticket-282/README.md new file mode 100644 index 00000000..a0f85199 --- /dev/null +++ b/project/ticket-282/README.md @@ -0,0 +1,24 @@ +# Ticket 282: Preserve accepted ticket intent when blocking execution + +- **ID**: ticket-282 +- **Owner**: agent:codex-heyasa-audit +- **Status**: IN_PROGRESS +- **Workflow state**: PUBLICATION +- **Created**: 2026-11-06 + +SESSION_EXECUTION_AUTHORIZATION: user requested autonomous audit/repair and explicitly instructed execution with existing consent, without repeated questions. Parent PLF-19975; existing source PLF-20371 / GitHub #340. Separate disjoint scope from native279 and foreign280. Source editing requires a genuine current protected controller lease. Independent Validator owns approval/merge. + +## Goal and scope + +Preserve nonempty accepted descriptions through first and repeated block transitions. Keep reason history, explicit notes, inputs/outputs/artifacts and runtime claim termination. Retain existing synthetic description for originally empty tickets. No dependency, API signature or schema changes. + +## Acceptance criteria + +- [x] AC-01: Native regression proves nonempty/repeated description preservation, reason history and outputs, and existing lifecycle/empty-description compatibility. +- [ ] AC-02: Governance, all8required checks and independent exact-head publication pass. + +## Validation and delivery + +Native ticket execution regressions:40passed,0skipped. Ruff and managed governance pass. Tests preserve full accepted snapshots including advisory radar, reason history, repeated CLI blocking, outputs/artifacts and an actual legacy empty-description record. Existing #340 is the producer request. Independent8check PR publication remains pending; source279 PR342 is undergoing fresh CI at ee37a21e0118. + +CI fixture correction: the running-claim test declares its accepted description explicitly, independent of advisory generation. The separate legacy-empty-record test remains. Native40tests, Python3.10.20 SDK lifecycle smoke, Ruff and governance pass; fresh protected matrix remains required. diff --git a/project/ticket-282/intent.json b/project/ticket-282/intent.json new file mode 100644 index 00000000..9dff564f --- /dev/null +++ b/project/ticket-282/intent.json @@ -0,0 +1,82 @@ +{ + "schema": "new-project.intent/v3", + "ticket": "ticket-282", + "summary": "Preserve accepted description when blocking a ticket while retaining reason history and clearing active execution claims", + "workstream": "application", + "classification": { + "kind": "BUG", + "priority": "P1", + "origin": "health" + }, + "allowedPaths": [ + "project/ticket-282/**", + "TODO.md", + "project/TICKETS.md", + "planfile/__init__.py", + "tests/test_ticket_execution.py" + ], + "forbiddenPaths": [ + "project/ticket-*/user-*.md" + ], + "stacks": [], + "dependsOn": [], + "conflictsWith": [], + "integrationTicket": null, + "delivery": { + "acceptedBaseSha": "edfa131b22ae8f6081d9c90489d9689f5075337a", + "targetBranch": "main", + "outcome": "Blocking a ticket preserves every nonempty accepted description and existing inputs/outputs, retains block reasons in history and explicit notes, clears active execution claims, and preserves legacy empty-description presentation.", + "nonGoals": [ + "No API signature/schema/dependency changes", + "No global GitHub managed-body roundtrip redesign; existing issue341 owns it", + "No foreign allocator280 changes or migration" + ], + "complexity": "S", + "estimatedMinutes": 30, + "budgets": { + "maxImplementationFiles": 2, + "maxAffectedComponents": 1, + "maxPublicInterfaceChanges": 0, + "maxRuntimeDependencies": 0 + }, + "architecture": { + "status": "accepted", + "decision": "Keep block_ticket as the shared SDK lifecycle transition; write synthetic blocker description only when no accepted description exists and preserve existing update/history/note machinery.", + "components": [ + { + "name": "Ticket execution lifecycle", + "paths": [ + "planfile/__init__.py", + "tests/test_ticket_execution.py" + ] + } + ], + "responsibilityChanges": false, + "interfaceChanges": [], + "dataChanges": [], + "ui": { + "impact": "none", + "states": [], + "evidence": [] + }, + "rollback": "Revert this bounded source change through independent protected delivery; never overwrite already recovered ticket descriptions." + }, + "runtimeDependencies": [], + "validation": [ + { + "criterion": "AC-01", + "commands": [ + "python -m pytest tests/test_ticket_execution.py -q" + ], + "evidence": "Pending native verification of nonempty and repeated blocking, reason history, output preservation and existing empty-description behavior." + }, + { + "criterion": "AC-02", + "commands": [ + "./project/governance-check.sh" + ], + "evidence": "Pending required governance, all8protected checks and independent exact-head review/merge." + } + ] + } +} diff --git a/tests/test_ticket_execution.py b/tests/test_ticket_execution.py index 35571bff..ab292a35 100644 --- a/tests/test_ticket_execution.py +++ b/tests/test_ticket_execution.py @@ -522,6 +522,7 @@ def test_block_ticket_clears_running_execution_claim(tmp_path): pf = Planfile(str(tmp_path)) ticket = pf.create_ticket( name="Run external task", + description="Accepted external task scope.", source=TicketSource(tool="shell"), execution=TicketExecution(state="pending"), ) @@ -532,7 +533,7 @@ def test_block_ticket_clears_running_execution_claim(tmp_path): blocked = pf.block_ticket(ticket.id, reason="external precondition missing") assert blocked is not None assert blocked.status == "blocked" - assert blocked.description == "BLOCKED: external precondition missing" + assert blocked.description == started.description assert blocked.execution is not None assert blocked.execution.state == "blocked" assert blocked.execution.assigned_to is None @@ -680,3 +681,85 @@ def unexpected_rebuild(*args, **kwargs): assert updated.execution.state == "ready" assert updated.execution.attempt == 1 assert pf.get_ticket(ticket.id, repair_index=False).model_dump(exclude={"sprint"}) == updated.model_dump(exclude={"sprint"}) + + +@pytest.mark.parametrize("description", [ + "## Accepted scope\n\n- Preserve the deployment contract.\n", + "Zaakceptowany zakres: zachowaj dane i uprawnienia.", + " ", +]) +def test_block_ticket_preserves_nonempty_accepted_description(tmp_path, description): + pf = Planfile(str(tmp_path)) + ticket = pf.create_ticket(name="Preserve accepted intent", description=description) + + blocked = pf.block_ticket(ticket.id, reason="waiting for an external prerequisite") + + assert ticket.description.startswith(description) + assert blocked.description == ticket.description + assert pf.get_ticket(ticket.id).description == ticket.description + assert blocked.history[-1]["reason"] == "waiting for an external prerequisite" + + +def test_repeated_block_preserves_intent_outputs_and_reason_history(tmp_path): + pf = Planfile(str(tmp_path)) + ticket = pf.create_ticket( + name="Resume the accepted work", + description="Accepted implementation and acceptance criteria must survive.", + inputs=TicketInputs(env_keys=["EXISTING_SETTING"], script="scripts/run.sh"), + outputs=TicketOutputs(notes=["Prior evidence"], artifacts=["proof.json"], + result={"accepted": True}), + execution=TicketExecution(state="pending"), + ) + started = pf.start_ticket(ticket.id, assigned_to="worker-1") + assert started.execution.state == "running" + + for reason, note in [("dependency unavailable", "First blocker"), + ("dependency still unavailable", "Second blocker")]: + blocked = pf.block_ticket(ticket.id, reason=reason, note=note, actor="worker-1") + assert blocked.description == ticket.description + assert blocked.inputs == ticket.inputs + assert blocked.outputs.artifacts == ["proof.json"] + assert blocked.outputs.result == {"accepted": True} + assert blocked.history[-1]["reason"] == reason + assert blocked.history[-1]["actor"] == "worker-1" + assert blocked.execution.state == "blocked" + assert blocked.execution.assigned_to is None + assert blocked.execution.lease_expires_at is None + assert blocked.execution.finished_at is not None + assert blocked.outputs.notes == ["Prior evidence", "First blocker", "Second blocker"] + assert [entry["reason"] for entry in blocked.history + if (entry.get("reason") or "").startswith("dependency")] == [ + "dependency unavailable", "dependency still unavailable"] + + +def test_ticket_block_command_preserves_accepted_description(tmp_path, monkeypatch): + from typer.testing import CliRunner + + from planfile.cli.commands import app + + monkeypatch.chdir(tmp_path) + pf = Planfile(str(tmp_path)) + ticket = pf.create_ticket(name="CLI blocking", description="## Accepted scope\nKeep this plan.") + runner = CliRunner() + for reason in ["not yet available", "still not available"]: + result = runner.invoke(app, ["ticket", "block", ticket.id, "--reason", reason]) + assert result.exit_code == 0, result.output + assert pf.get_ticket(ticket.id).description == ticket.description + assert pf.get_ticket(ticket.id).history[-1]["reason"] == reason + + +def test_block_ticket_keeps_legacy_empty_description_presentation(tmp_path): + pf = Planfile(str(tmp_path)) + ticket = pf.create_ticket(name="Legacy empty description") + # Current creation adds advisory radar prose. Load a real legacy empty + # record so this exercises the empty-description compatibility boundary. + sprint_path = tmp_path / ".planfile" / "sprints" / "current.yaml" + stored = yaml.safe_load(sprint_path.read_text(encoding="utf-8")) + stored["sprint"]["tickets"][ticket.id]["description"] = "" + sprint_path.write_text(yaml.safe_dump(stored, sort_keys=False), encoding="utf-8") + assert pf.get_ticket(ticket.id).description == "" + + blocked = pf.block_ticket(ticket.id, reason="external precondition missing") + + assert blocked.description == "BLOCKED: external precondition missing" + assert blocked.history[-1]["reason"] == "external precondition missing"