[AISOS-2294] Add decompose draft review step before Jira task creation

[ekuris-redhat]

Summary

This pull request implements an interactive, draft-based planning review flow for epic decomposition and task generation workflows. It introduces Pydantic models for draft representation, robust Jira attachment helpers and management utilities, comment commands and natural language feedback revision logic, and integrates a State Consistency Guard with rollback capabilities in the orchestrator worker. Ultimately, this allows human-in-the-loop validation, modification, and direct provisioning of generated tickets from structured draft JSONs attached to Jira issues.

Changes

Models & Schema Verification

• Created src/forge/models/draft.py defining DraftItem (supporting an epic_key field to correctly map Tasks to parent Epics) and ForgeDecompositionDraft Pydantic v2 models, enforcing unique sequential item IDs and exclusion flags (via an excluded boolean property).
• Exported the draft models in src/forge/models/__init__.py.

Jira Integrations & Utilities

• Modified src/forge/integrations/jira/client.py to add robust Jira attachment helpers (get_attachments, download_attachment, delete_attachment, delete_attachments_by_name, edit_comment with robust retry logic, and add_attachment) with automatic rate-limit and retry logic.
• Created src/forge/workflow/utils/draft_manager.py implementing DraftManager to handle JSON draft serialization, secure downloading, deserialization, single-draft attachment constraints, and transactional in-memory draft modifications (add, update, remove, exclude).

Comment Command & Natural Language LLM Parsing

• Enhanced src/forge/workflow/utils/comment_classifier.py by adding CommentType.COMMAND and introducing regex-based comment command classification.
• Implemented parse_comment_command to extract operations and arguments for /forge add, /forge update, /forge remove, /forge exclude, and /forge approve.
• Created prompt template src/forge/prompts/v1/revision-draft.md to feed draft edits and natural language feedback into an LLM chain.
• Added revise_draft_with_feedback in src/forge/integrations/agents/agent.py to revise draft structures using LLM feedback with a clean, Markdown-stripping JSON parsing utility.

Orchestration & State Machine Integration

• Modified src/forge/workflow/nodes/epic_decomposition.py and src/forge/workflow/nodes/task_generation.py to conditionally bypass or enter the draft review gate (pausing at PENDING_APPROVAL, implementing an empty-draft guard in the non-YOLO path for epic decomposition, and writing markdown previews with a 32,767 character/15-item truncation threshold).
• Modified src/forge/orchestrator/worker.py to capture comments while paused, applying either /forge mutation commands or leading whitespace-tolerant ! natural language revisions on attached draft JSONs.
• Implemented State Consistency Guard (BR-006) in the worker to automatically roll back to the previously attached draft version and report failures upon any processing errors.
• Integrated automated Jira ticket provisioning upon approval comments (/forge approve) or transition label events (forge:plan-approved, forge:task-approved) inside the orchestrator worker, skipping excluded items and ensuring attachment deletion only after successful creation of all items.

Documentation Updates

• Updated CLAUDE.md, docs/guide/labels.md, docs/guide/feature-workflow.md, and docs/developer-guide.md to reflect interactive comment commands, workflow diagrams, and state-machine characteristics.

Implementation Notes

• Single Draft File Constraint: Ensures only one stories draft (forge-stories-draft.json) and one tasks draft (forge-tasks-draft.json) exists at any time on a ticket by systematically deleting obsolete attachments before uploading newly generated ones.
• State Consistency Guard (BR-006): Ensures that any validation or execution error during a draft modification rolls back the draft attachment to the pre-modification version, ensuring no corrupted or partial JSONs are persisted.
• Truncation Boundary (BR-003): Automatically formats a condensed markdown table instead of verbose task descriptions if the preview exceeds 32,767 characters or contains over 15 items, mitigating Jira API limits.
• YOLO Mode Bypass: Detects the forge:yolo label or global yolo_mode to skip the draft review loop and provision issues immediately.

Testing

• Unit Testing: Thoroughly covered model validation sequences, comment classification regexes, mutation algorithms, custom mock LLM agents, and draft manager behaviors.
• Integration Testing: Created tests/workflow/test_draft_review_flow.py verifying full end-to-end flows: YOLO bypass, draft attachments, comment comment modifications, LLM-based draft revisions, truncation rules, and state rollbacks on execution failures.
• Test Locations:
  • tests/unit/models/test_draft.py
  • tests/unit/integrations/jira/test_client_attachments.py
  • tests/unit/workflow/utils/test_draft_manager.py
  • tests/unit/workflow/test_comment_classifier.py
  • tests/workflow/utils/test_comment_command.py
  • tests/unit/integrations/agents/test_agent.py
  • tests/unit/orchestrator/test_worker.py
  • tests/unit/workflow/nodes/test_task_generation.py
  • tests/workflow/test_draft_review_flow.py

Related Tickets

• AISOS-2294
• AISOS-2298
• AISOS-2299
• AISOS-2300
• AISOS-2301
• AISOS-2302
• AISOS-2303
• AISOS-2304
• AISOS-2305
• AISOS-2306
• AISOS-2307
• AISOS-2308
• AISOS-2309
• AISOS-2310
  Fixed Add decompose draft review step before Jira task creation #218

---

Generated by Forge SDLC Orchestrator

[ekuris-redhat]

! Please address the following issues found during review:

1. Missing empty-draft guard in epic decomposition (non-YOLO path)

In src/forge/workflow/nodes/task_generation.py, the non-YOLO path correctly checks if not proposed_tasks_list: and returns a retry state
before touching Jira. The equivalent path in src/forge/workflow/nodes/epic_decomposition.py has no such check. If the agent returns
zero epics in non-YOLO mode, the code creates an empty ForgeDecompositionDraft, uploads it, posts a comment with an empty table, and
pauses the workflow with nothing for the human to approve. Please add the same guard before the draft creation block in decompose_epics:
if epics_data is empty after the LLM call, return a retry state with an appropriate last_error, matching the YOLO path's else branch.

2. edit_comment skips retry logic

In src/forge/integrations/jira/client.py, the edit_comment method uses client = await self._get_client() and calls client.put(...)
directly. Every other new Jira helper added in this PR (download_attachment, delete_attachment, get_attachments, add_attachment) routes
through _request_with_retry. The PR explicitly advertises rate-limit and retry logic as a feature, but edit_comment will fail
immediately on transient 429 responses. Please refactor it to use _request_with_retry like the other helpers.

3. Revision comment detection inconsistency

In src/forge/orchestrator/worker.py, the revision comment check uses comment_body.startswith("!"). The classify_comment function in
comment_classifier.py uses _REVISION_PATTERN = re.compile(r"^\s*!") which allows leading whitespace. A comment with a leading space
would be classified as FEEDBACK by the classifier but not caught as a revision comment by the worker, falling through to trigger full
regeneration instead of draft JSON revision. Please change the worker check to use bool(re.match(r"^\s*!", comment_body)) to match the
classifier.

[ekuris-redhat]

Forge is addressing PR review feedback now. This status update is informational.

[ekuris-redhat]

Forge is addressing PR review feedback now. This status update is informational.

[ekuris-redhat]

Forge is addressing PR review feedback now. This status update is informational.

[ekuris-redhat]

Forge is addressing PR review feedback now. This status update is informational.

[ekuris-redhat]

Forge is addressing PR review feedback now. This status update is informational.

[ekuris-redhat]

Forge is addressing PR review feedback now. This status update is informational.

[ekuris-redhat]

Hey, a few things I'd like addressed before we move forward with this one.

First, and most importantly: the .mypy_cache/3.11/ directory got committed — 18 binary cache files are showing up in the diff.
These are local mypy artifacts that should never be tracked. Please remove all of them from the branch and also add
.mypy_cache/ to .gitignore since it's currently missing from there.

Duplicate code in the worker: In worker.py, the block that finds the original review comment and edits it appears twice in a
row — once in the forge command handler and once in the revision comment handler. These are nearly identical. Please extract
that logic into a small helper so we don't have to maintain two copies.

format_review_comment duplication: The stories and tasks branches in draft_manager.py are about 95% identical. The only things
that differ are the header text, the field label, and the approval label. Please collapse them into a single helper that
accepts those as parameters.

Unnecessary LangChain wrapping: In revise_draft_with_feedback, load_prompt already returns a fully formatted string. Wrapping
it in PromptTemplate.from_template("{prompt_text}") just to pass it through is extra ceremony that doesn't add anything. A
direct call to model.ainvoke(prompt_text) would do the same thing with fewer moving parts.

A few smaller things:

The nested from datetime import datetime inside the worker function body should move to the top of the file alongside the
existing from datetime import UTC.

available_repos: Any = set() in epic_decomposition.py should use the concrete type set[str] instead of Any.

In get_attachments, each attachment dict gets both a content and a content_url key pointing to the same value. One is enough.

The _validate_item_params method in DraftManager manually replicates the type checks that Pydantic's DraftItem.model_validate
would already enforce. Consider leaning on Pydantic for this instead.

Finally, provision_epics_from_draft and provision_tasks_from_draft are called from both the worker and the route functions. The
guard on epic_keys prevents double execution, but the split ownership is confusing. Please add a comment explaining why both
call sites need to exist, or consolidate them.

[ekuris-redhat]

Forge is addressing PR review feedback now. This status update is informational.

[ekuris-redhat]

Forge is addressing PR review feedback now. This status update is informational.

[ekuris-redhat]

A few concrete issues I want to flag before merging:

1. format_review_comment ignores the module's own constants

draft_manager.py defines FORGE_STORIES_DRAFT_FILENAME and FORGE_TASKS_DRAFT_FILENAME at module level, but format_review_comment
hardcodes the literal strings "forge-stories-draft.json" and "forge-tasks-draft.json" in two places. If the filenames ever
change, this method will silently diverge. Replace with the constants.

2. getattr(settings, "yolo_mode", False) is stale — the field exists

This PR adds yolo_mode: bool = Field(default=False) to config.py, which means the getattr fallback in epic_decomposition.py and
task_generation.py is unnecessary. Use settings.yolo_mode directly.

3. Duplicate ValidationError import inside _validate_item_params

from pydantic import ValidationError is already imported at the top of draft_manager.py. The same import inside
_validate_item_params's body is redundant — remove it.

4. YOLO detection copy-pasted 4 times

The same three-component check — "forge:yolo" in labels or getattr(settings, "yolo_mode", False) or state.get("yolo_mode",
False) — appears identically in epic_decomposition.py, task_generation.py, plan_approval.py, and task_approval.py. This should
be a shared helper so all four sites stay in sync.

5. provision_epics_from_draft and provision_tasks_from_draft use Any for typed parameters

Both functions are declared (state: Any, jira: Any). They should use WorkflowState and JiraClient.

[ekuris-redhat]

Forge is addressing PR review feedback now. This status update is informational.

[ekuris-redhat]

Forge is addressing PR review feedback now. This status update is informational.