devops-bot-sdk 1.4.47__tar.gz → 1.4.58__tar.gz

{devops_bot_sdk-1.4.47 → devops_bot_sdk-1.4.58}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devops-bot-sdk
-Version: 1.4.47
+Version: 1.4.58
 Summary: DevOps Bot Desktop SDK — thin client for the AgentOS Electron desktop app
 Author: noumanaziz2128
 License-Expression: LicenseRef-Proprietary

{devops_bot_sdk-1.4.47 → devops_bot_sdk-1.4.58}/devops_bot_sdk.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devops-bot-sdk
-Version: 1.4.47
+Version: 1.4.58
 Summary: DevOps Bot Desktop SDK — thin client for the AgentOS Electron desktop app
 Author: noumanaziz2128
 License-Expression: LicenseRef-Proprietary

{devops_bot_sdk-1.4.47 → devops_bot_sdk-1.4.58}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "devops-bot-sdk"
-version = "1.4.47"
+version = "1.4.58"
 description = "DevOps Bot Desktop SDK — thin client for the AgentOS Electron desktop app"
 readme = "README.md"
 license = "LicenseRef-Proprietary"

{devops_bot_sdk-1.4.47 → devops_bot_sdk-1.4.58}/sdk/__init__.py

@@ -1,6 +1,6 @@
 """AgentOS Desktop SDK — thin HTTPS/SSE client for the Electron app.
 
-Version: 1.4.47
+Version: 1.4.58
 
 Public surface:
   BackendClient.from_config()        — create client from ~/.agentos/config.toml
@@ -30,7 +30,7 @@ Rules:
   - All data egress through submit_webhook only
 """
 
-__version__ = "1.4.47"
+__version__ = "1.4.58"
 __author__  = "AgentOS"
 
 from sdk.client import BackendClient

{devops_bot_sdk-1.4.47 → devops_bot_sdk-1.4.58}/sdk/client.py

@@ -58,7 +58,7 @@ def _notify_status(task_id: str, status: str) -> None:
             pass
 
 
-SDK_VERSION    = "1.4.47"
+SDK_VERSION    = "1.4.58"
 _POLL_INTERVAL = 3.0
 _POLL_TIMEOUT  = 600.0
 _ORCHESTRATE_TIMEOUT      = 2700.0  # 45 min — covers approval wait + VPS execution time
@@ -868,6 +868,34 @@ class BackendClient:
             logger.warning("client.create_task_ml error err=%s", exc)
             return None
 
+    async def add_comment(self, task_id: str, body: str) -> bool:
+        """POST /tasks-ml/{id}/comments — add a comment to a ticket (best-effort).
+
+        Used by the validation gate to post AI feedback (prefixed with an
+        [AI Comments] label) when an Epic/Story is rejected. JSON body: {"body": ...}.
+        Returns True on 2xx.
+        """
+        from sdk.config import BE_DEFAULT_URL
+
+        url = f"{BE_DEFAULT_URL.rstrip('/')}/tasks-ml/{task_id}/comments"
+        headers = {
+            **self._headers,           # includes Content-Type: application/json
+            "accept": "*/*",
+            "developer-name": "null",
+            "product": "",
+        }
+        try:
+            async with httpx.AsyncClient(timeout=20.0) as client:
+                resp = await client.post(url, json={"body": str(body)}, headers=headers)
+            if resp.status_code >= 400:
+                logger.warning("client.add_comment failed task=%s status=%s body=%s",
+                               task_id, resp.status_code, resp.text[:200])
+                return False
+            return True
+        except Exception as exc:  # noqa: BLE001
+            logger.warning("client.add_comment error task=%s err=%s", task_id, exc)
+            return False
+
     async def log_activity(self, activity: str) -> bool:
         """POST /ml-api/agent-activity — emit an agent activity event (best-effort).
 

{devops_bot_sdk-1.4.47 → devops_bot_sdk-1.4.58}/sdk/ipc/handlers.py

@@ -210,6 +210,17 @@ def _build_local_prompt(
             "before changing it.\n\n"
             + human_instructions.strip()
         )
+    # 1b. If a PRD is present (a dev Story was converted to this Task with its PRD
+    #     folded into the description), it is the AUTHORITATIVE spec — build the
+    #     whole feature to satisfy it end-to-end.
+    if user_input and _PRD_MARKER in user_input:
+        parts.append(
+            "This task includes a PRD (Product Requirements Document) in its description "
+            "below. Treat the PRD as the AUTHORITATIVE specification: implement the WHOLE "
+            "feature to satisfy its Functional Requirements, Non-Functional Requirements, "
+            "and Acceptance Criteria, following the PRD end-to-end. Do not narrow or skip "
+            "any part of the PRD's scope."
+        )
     # 2. Distilled plan (acceptance criteria + steps) — the compact, actionable
     #    content the backend planner derived from the full description.
     sp = structured_plan or {}
@@ -231,6 +242,15 @@ def _build_local_prompt(
             "above are authoritative if anything conflicts) ===\n"
             + _clip_text(user_input.strip())
         )
+    # House standards — if this task produces a PRD document, hold it to the
+    # same standard format the bot uses everywhere else (a Task converted from a
+    # Story keeps its PRD directive in the instructions).
+    if _wants_prd(human_instructions) or _wants_prd(user_input):
+        parts.append(
+            "If you create a PRD / product-requirements document (e.g. a PRD.md), "
+            "write it in this STANDARD PRD FORMAT (keep the numbered headings):\n"
+            + _PRD_FORMAT
+        )
     if git_managed:
         # The target is a git repo the SDK manages — it branches before and
         # commits/pushes/opens the PR after, so the agent must not touch git here.
@@ -360,13 +380,78 @@ _MAX_EPIC_STORIES = int(os.getenv("AGENTOS_MAX_EPIC_STORIES", "") or 8)
 # Label recorded in the ticket's modelUsed on Epic completion.
 _EPIC_MODELS = [m.strip() for m in (os.getenv("AGENTOS_EPIC_MODELS", "") or "claude-code").split(",") if m.strip()]
 
+# ── Standard output formats ─────────────────────────────────────────────────
+# One house style for every generated artifact so Epics, Stories and PRDs read
+# consistently across tickets. Referenced by the generation prompts below.
+_EPIC_FORMAT = (
+    "## Epic\n<concise epic title>\n\n"
+    "## Overview\n<1-2 paragraph summary of the goal and context>\n\n"
+    "## Business Value / Goal\n<why this matters; the outcome it drives>\n\n"
+    "## Scope\n**In scope:** <what is included>\n**Out of scope:** <what is not>\n\n"
+    "## User Stories\n1. <story title> — <one-line summary>\n2. <story title> — <one-line summary>\n\n"
+    "## Epic-level Acceptance Criteria\n- <observable, high-level pass/fail criteria>\n\n"
+    "## Dependencies & Risks\n- <key dependencies, assumptions, risks>"
+)
+_USER_STORY_FORMAT = (
+    "## User Story\n"
+    "As a <role>, I want <capability>, so that <benefit>.\n\n"
+    "## Acceptance Criteria\n"
+    "- Given <context>, when <action>, then <expected outcome>.\n"
+    "- <list every testable criterion, Gherkin Given/When/Then style>\n\n"
+    "## Notes & Constraints\n"
+    "- <context, dependencies, constraints; for software work: affected files/modules & patterns to follow>\n\n"
+    "## Definition of Done\n"
+    "- Delivered against the acceptance criteria above\n"
+    "- Reviewed / validated (for software: tests added & passing)\n"
+    "- Documentation updated where relevant"
+)
+_PRD_FORMAT = (
+    "# PRD: <title>\n\n"
+    "## 1. Overview\n<what the feature is and why, in brief>\n\n"
+    "## 2. Goals & Non-Goals\n<what it must achieve; what is explicitly out of scope>\n\n"
+    "## 3. Current Behaviour & Context\n<the existing system/modules this touches — "
+    "grounded in the REAL codebase: files, components, current flow>\n\n"
+    "## 4. How It Works — Mechanism\n<the core mechanism end-to-end: the exact flow of "
+    "control and data, step by step, from trigger/input to output/persistence. Describe "
+    "how the feature actually functions, not just what it does>\n\n"
+    "## 5. Architecture & Components\n<components/modules/services involved and their "
+    "responsibilities; where new code lives; how they interact>\n\n"
+    "## 6. Data Model & Schema\n<entities, fields + types, relationships, indexes, and "
+    "any migrations / schema changes>\n\n"
+    "## 7. API / Interface Contracts\n<each endpoint or interface: HTTP method + path, "
+    "request shape, response shape, status codes, auth. Include example payloads>\n\n"
+    "## 8. Detailed Logic & Business Rules\n<algorithms, validation rules, state "
+    "transitions, sequence of operations, ordering/idempotency, concurrency>\n\n"
+    "## 9. Data Flow & Integrations\n<how data moves between components/services; "
+    "external systems, events, queues, third-party APIs>\n\n"
+    "## 10. Error Handling & Edge Cases\n<failure modes, validation errors, retries, "
+    "timeouts, boundary conditions, empty/duplicate/large inputs>\n\n"
+    "## 11. Security & Performance (Non-Functional)\n<authn/authz, input hardening, "
+    "secrets, rate limits, performance/scale targets, accessibility where relevant>\n\n"
+    "## 12. Testing Strategy\n<unit / integration / e2e coverage and the key test cases "
+    "that prove each requirement>\n\n"
+    "## 13. Acceptance Criteria\n<observable, testable pass/fail tied to the mechanism>\n\n"
+    "## 14. Dependencies, Risks & Rollout\n<dependencies, assumptions, risks, migration "
+    "and rollout/phasing>"
+)
+
 
 def _build_epic_prompt(jira_key: str, summary: str, description: str | None,
                        human_instructions: str | None) -> str:
     """Read-only prompt that turns an Epic into a decomposition JSON."""
     parts: list[str] = [
-        "You are decomposing a JIRA EPIC into implementable work. This is ANALYSIS "
-        "ONLY — do NOT create, edit, or delete any file.",
+        "You are decomposing a JIRA EPIC into implementable user stories. This is "
+        "ANALYSIS ONLY — do NOT create, edit, or delete any file.",
+        "Faithfulness (read first — this prevents hallucinated stories):\n"
+        "- Derive stories ONLY from what the epic actually states or clearly implies. "
+        "Do NOT invent features, scope, integrations, tools, or requirements that are "
+        "not grounded in the epic (or, for software, in the REAL codebase you inspect).\n"
+        "- If something needed is missing or ambiguous, capture it as an open question "
+        "in that story's Notes — do NOT fabricate a solution.\n"
+        "- Prefer fewer, well-grounded stories over many speculative ones. Every story "
+        "must trace back to something in the epic.\n"
+        "- This epic may be for ANY domain (software, Finance, HR, operations, …). Match "
+        "the stories to the epic's actual domain; do not assume it is software.",
         f"=== EPIC {jira_key} ===\nSummary: {summary}",
     ]
     if description and description.strip():
@@ -378,18 +463,20 @@ def _build_epic_prompt(jira_key: str, summary: str, description: str | None,
             + human_instructions.strip()
         )
     parts.append(
-        "First understand the existing codebase in this directory (read CLAUDE.md, "
-        "use graphify / Read / Glob / Grep) so the stories fit the REAL architecture. "
-        "Then produce the decomposition.\n\n"
+        "Ground your work first: if this is a SOFTWARE project, inspect the existing "
+        "codebase in this directory (read CLAUDE.md, use graphify / Read / Glob / Grep) "
+        "so the stories fit the REAL architecture. For a NON-software epic (Finance, HR, "
+        "operations, …), ground the stories in the epic's stated details and any "
+        "reference material present — never in invented facts. Then produce the "
+        "decomposition.\n\n"
         "Output ONLY a single fenced ```json block and nothing after it, with shape:\n"
         "{\n"
-        '  "epic_description": "A detailed description for the epic: a full user-story '
-        "write-up covering goal, the user stories, acceptance criteria and scope.\",\n"
+        '  "epic_description": "The epic write-up in the EPIC FORMAT below (Markdown).",\n'
         '  "plan": "An ordered, numbered high-level implementation plan.",\n'
         '  "stories": [\n'
         '    {\n'
         '      "summary": "Short imperative story title (a JIRA task summary)",\n'
-        '      "description": "Detailed description: what to build + acceptance criteria.",\n'
+        '      "description": "The story in the USER STORY FORMAT below (Markdown).",\n'
         '      "humanInstructions": "Operator instructions to implement THIS story. MUST '
         "repeat the same project location/path and constraints from the epic so the "
         'coding run works in the right place.",\n'
@@ -397,12 +484,16 @@ def _build_epic_prompt(jira_key: str, summary: str, description: str | None,
         '      "points": 5\n'
         "    }\n"
         "  ]\n"
-        "}\n"
+        "}\n\n"
         "Create as many stories as the epic genuinely needs (do not pad or truncate "
         "artificially); each story must be independently implementable.\n"
         "assigneeEmail is OPTIONAL per story: set it ONLY when the epic explicitly "
         "assigns that specific work to a named person/email (e.g. 'assign the API to "
-        "alice@x.com'); otherwise omit it."
+        "alice@x.com'); otherwise omit it.\n\n"
+        "=== EPIC FORMAT (epic_description MUST follow this exactly) ===\n"
+        + _EPIC_FORMAT
+        + "\n\n=== USER STORY FORMAT (every story.description MUST follow this exactly) ===\n"
+        + _USER_STORY_FORMAT
     )
     return "\n\n".join(parts)
 
@@ -459,6 +550,117 @@ def _epic_inherited_fields(task: dict) -> dict:
     return {k: v for k, v in fields.items() if v}
 
 
+# ── Ticket validation gate (Epics + USER-driven Stories) ────────────────────
+# A strict quality gate: before the bot actions an Epic or a USER-created Story it
+# checks the ticket meets the required standard. On failure it posts a harsh,
+# technical comment (prefixed with the label below) and moves the ticket to
+# Backlog. SYSTEM-created Stories (spun off an Epic by the bot) are trusted and
+# skip validation. A later run re-validates; once the gaps are addressed in the
+# description / Human Instructions, it passes and the normal flow proceeds.
+_AI_COMMENT_LABEL = "[AI Comments]"
+
+
+def _build_validation_prompt(kind: str, jira_key: str, summary: str,
+                             description: str | None, human: str | None) -> str:
+    k = kind.upper()
+    parts: list[str] = [
+        f"You are a STRICT ticket-quality gate for a JIRA {k}. Decide whether this "
+        "ticket meets the required standard to be actioned autonomously. Be HARSH: if "
+        "the required structure or information is not strictly present, REJECT it — a "
+        "vague or under-specified ticket must NOT pass.",
+        f"=== {k} {jira_key} ===\nSummary: {summary or '(none)'}",
+        "Description:\n" + (_clip_text(description.strip()) if description and description.strip() else "(none provided)"),
+        "Human Instructions:\n" + (human.strip() if human and human.strip() else "(none provided)"),
+    ]
+    parts.append(
+        "A VALID ticket MUST have:\n"
+        "- A clear, unambiguous goal and scope (no hand-waving).\n"
+        "- Explicit Human Instructions: for codebase work, the repository link(s) "
+        "and/or file path(s), the branch/PR convention, and build/run/test steps.\n"
+        "- Observable, testable acceptance criteria.\n"
+        + ("- Enough concrete detail to decompose into independent user stories.\n"
+           if kind == "epic" else
+           "- A clear 'As a <role>, I want <capability>, so that <benefit>' intent plus "
+           "testable acceptance criteria.\n")
+        + "- Any THIRD-PARTY INTEGRATION or human-effort dependency (API keys, OAuth "
+        "credentials, external accounts, secrets, manual provisioning, DNS, billing) "
+        "MUST be named explicitly WITH who provides it. If such a dependency is implied "
+        "but undefined/missing, REJECT.\n\n"
+        "Output ONLY a fenced ```json block, nothing else:\n"
+        "{\n"
+        '  "valid": true or false,\n'
+        '  "comment": "When invalid: a concise, TECHNICAL rejection that lists EXACTLY '
+        "what is missing or ambiguous and must be added. Use precise engineering "
+        "terminology (API contract, data model/schema, auth/OAuth flow, env/config, "
+        "acceptance criteria, target repository/branch, integration credentials & "
+        'ownership). When valid: empty string."\n'
+        "}"
+    )
+    return "\n\n".join(parts)
+
+
+def _parse_validation(text: str | None) -> tuple[bool, str]:
+    """(valid, comment) from the validator's JSON output. Defaults to invalid."""
+    obj = _extract_json_block(text) or {}
+    return bool(obj.get("valid")), str(obj.get("comment") or "").strip()
+
+
+async def _validate_ticket_or_reject(
+    client: BackendClient, task: dict, kind: str, payload: dict,
+    send: Callable, thread_id: str,
+) -> bool:
+    """Strict gate. Returns True to proceed, False if the ticket was rejected
+    (comment posted + moved to Backlog). Fails OPEN if the validator can't run —
+    we never block a ticket on our own infrastructure error."""
+    from sdk import local_exec
+
+    tid = str(task.get("id", ""))
+    jira_key = task.get("jiraIssueKey") or task.get("jiraKey", "") or kind.upper()
+    project_path = _resolve_local_project_path(task, payload)
+
+    await send(Envelope(
+        type="step_update", thread_id=thread_id,
+        data={"jira_task_id": tid, "task_id": tid,
+              "current_step": f"{kind.title()} {jira_key}: validating ticket against the standard"},
+    ).model_dump())
+
+    res = await local_exec.run_claude_local(
+        _build_validation_prompt(kind, jira_key, task.get("summary", "") or "",
+                                 task.get("description"), task.get("humanInstructions")),
+        project_path, allowed_tools=_RECON_ALLOWED_TOOLS,  # read-only judgment
+        github_token=await client.github_token(),
+    )
+    if not res.get("ok"):
+        await client.log_activity(
+            f"{kind} {jira_key}: validation could not run ({(res.get('error') or '')[:120]}) — proceeding"
+        )
+        return True  # fail-open on validator infra error
+
+    valid, comment = _parse_validation(res.get("result"))
+    if valid:
+        await send(Envelope(
+            type="step_update", thread_id=thread_id,
+            data={"jira_task_id": tid, "current_step": f"{kind.title()} {jira_key}: validation passed"},
+        ).model_dump())
+        return True
+
+    # Rejected — post a labelled, technical comment and move to Backlog.
+    fallback = ("This ticket does not meet the required standard. Provide: a clear goal "
+                "and scope; explicit Human Instructions (target repository/branch and/or "
+                "file paths, PR convention, build/run/test steps); testable acceptance "
+                "criteria; and the credentials/ownership for any third-party integration.")
+    body = f"{_AI_COMMENT_LABEL}\n\n{comment or fallback}"
+    await client.add_comment(tid, body)
+    await client.move_to_backlog(tid)
+    await client.log_activity(f"{kind} {jira_key}: REJECTED by validation gate — commented + moved to Backlog")
+    await send(Envelope(
+        type=Envelope.TYPE_ERROR, thread_id=thread_id,
+        data={"code": f"{kind.upper()}_VALIDATION_REJECTED", "task_id": tid,
+              "message": (comment or fallback)[:300]},
+    ).model_dump())
+    return False
+
+
 async def _handle_epic(
     client: BackendClient, task: dict, payload: dict, send: Callable, thread_id: str,
 ) -> None:
@@ -537,6 +739,7 @@ async def _handle_epic(
             **inherited,
             "type": "Story",   # Epic decomposes into user Stories; a Story later
                                # becomes a Task (see _handle_story) when it is run.
+            "drivenBy": "SYSTEM",  # bot-created → trusted, skips the validation gate
             "status": "To Do",
             "summary": str(st.get("summary", "")).strip()[:250],
             "description": str(st.get("description", "") or "")[:20000],
@@ -582,12 +785,34 @@ def _wants_prd(text: str | None) -> bool:
     return bool(text and _PRD_RE.search(text))
 
 
+# Signals that a ticket is DEVELOPMENT work (→ always gets a PRD). Deliberately
+# code-specific so Finance/HR/ops tickets don't false-positive (they get a PRD
+# only when explicitly requested).
+_DEV_RE = re.compile(
+    r"github\.com/|gitlab\.com/|bitbucket\.org/|\b(?:repo(?:sitory)?|codebase|"
+    r"source\s*code|frontend|front-end|back-?end|pull\s+requests?|merge\s+requests?|"
+    r"\bPRs?\b|feature\s+branch|create\s+a?\s*branch|commit|deploy(?:ment)?|compile|"
+    r"build\s+pipeline|microservice|endpoint|api\s+contract|database\s+migration|"
+    r"unit\s+test)\b",
+    re.I,
+)
+
+
+def _is_dev_task(text: str | None) -> bool:
+    """True when the text clearly describes software-development work."""
+    return bool(text and _DEV_RE.search(text))
+
+
 def _build_prd_prompt(jira_key: str, summary: str, user_story: str | None,
                       human_instructions: str | None) -> str:
-    """Read-only prompt that produces a PRD (Markdown) for a user story."""
+    """Read-only prompt that produces a TECHNICAL PRD (Markdown) for a user story."""
     parts: list[str] = [
-        "Write a PRD (Product Requirements Document) for the user story below. This is "
-        "ANALYSIS ONLY — do NOT create, edit, or delete any file.",
+        "Write a TECHNICAL PRD (Product Requirements Document) for the user story below. "
+        "It must fully specify the MECHANISM — how the feature works end-to-end "
+        "(architecture, components, data model, API/interface contracts, control & data "
+        "flow, business logic, error handling) — in enough detail that a developer can "
+        "implement it directly from the PRD without guessing. This is ANALYSIS ONLY — do "
+        "NOT create, edit, or delete any file.",
         f"=== USER STORY {jira_key} ===\nSummary: {summary}",
     ]
     if user_story and user_story.strip():
@@ -595,11 +820,17 @@ def _build_prd_prompt(jira_key: str, summary: str, user_story: str | None,
     if human_instructions and human_instructions.strip():
         parts.append("Operator instructions:\n" + human_instructions.strip())
     parts.append(
-        "Explore the codebase (CLAUDE.md, graphify, Read/Glob/Grep) to ground the PRD in "
-        "the REAL system. Output ONLY the PRD as Markdown — no preamble, no code edits — "
-        "with sections: Overview, Goals & Success Metrics, User Stories, Functional "
-        "Requirements, Non-Functional Requirements, Acceptance Criteria, Out of Scope, "
-        "Dependencies & Risks."
+        "Ground the PRD in reality — for software, FIRST understand the current codebase "
+        "STRUCTURE (folder layout, key modules, existing patterns, data models, APIs) via "
+        "CLAUDE.md, graphify and Read/Glob/Grep, then specify the mechanism against the "
+        "REAL files, modules, data models and APIs that exist; for a non-software task, "
+        "ground it in "
+        "the story's stated details and mark technical sections that don't apply as "
+        "'N/A'. Do NOT invent requirements, systems, endpoints, or facts not supported by "
+        "the story or the code you inspect. Output ONLY the PRD as Markdown — no preamble, "
+        "no code edits — following this PRD FORMAT exactly (keep the numbered section "
+        "headings):\n\n"
+        + _PRD_FORMAT
     )
     return "\n\n".join(parts)
 
@@ -621,14 +852,25 @@ async def _handle_story(
     summary = task.get("summary", "") or ""
     user_story = task.get("description") or ""
     human = task.get("humanInstructions")
-    wants_prd = _wants_prd(human) or _wants_prd(user_story)
-
+    # STEP 1 — validate whether this is a CODEBASE (development) task: repo links /
+    # file paths in the instructions, or dev signals (PRs, branches, endpoints,
+    # deploy, …). A codebase task ALWAYS gets a technical PRD built from the current
+    # codebase; other domains (Finance, HR, …) get one only when explicitly asked.
+    has_repo = bool(_extract_repo_targets(human)) or bool(_extract_repo_targets(user_story))
+    is_codebase_task = has_repo or _is_dev_task(human) or _is_dev_task(user_story)
+    wants_prd = is_codebase_task or _wants_prd(human) or _wants_prd(user_story)
+
+    if is_codebase_task:
+        step = ("validated as a codebase task — building a technical PRD from the "
+                "current codebase, then converting to Task")
+    elif wants_prd:
+        step = "generating the requested PRD, then converting to Task"
+    else:
+        step = "converting to Task"
     await send(Envelope(
         type="step_update", thread_id=thread_id,
         data={"jira_task_id": tid, "task_id": tid,
-              "current_step": f"Story {jira_key}: "
-                              + ("generating PRD, then " if wants_prd else "")
-                              + "converting to Task"},
+              "current_step": f"Story {jira_key}: {step}"},
     ).model_dump())
 
     # Idempotent: if a PRD is already in the description, don't regenerate it or
@@ -1039,6 +1281,40 @@ async def _code_one_repo(
     except Exception:  # noqa: BLE001
         branch_info = None
 
+    # 3a. Technical PRD for a CODEBASE task that doesn't have one yet. A Task created
+    #     directly (not via a Story) may carry only a user-story/feature description —
+    #     for codebase work we first turn the recon understanding into a technical PRD
+    #     and build to it, exactly like a Story-derived Task. Resumes the recon session
+    #     (already understands the codebase) so it's cheap; persists the PRD to the
+    #     ticket and to pending (shared → other repos reuse it and skip regeneration).
+    #     Skipped when a PRD is already present, on a resume, or for non-git targets.
+    if (is_git and recon_session and not resume_session_id
+            and _PRD_MARKER not in (pending.get("user_input") or "")):
+        await send(Envelope(
+            type="step_update", thread_id=thread_id,
+            data={"status": "running",
+                  "current_step": f"[{name}] Codebase task — writing a technical PRD from the codebase"},
+        ).model_dump())
+        prd_res = await local_exec.run_claude_local(
+            "Using your exploration above, write a TECHNICAL PRD for this task that fully "
+            "specifies the mechanism (how it works end-to-end) against the REAL code you "
+            "found. Output ONLY the PRD as Markdown, following this format exactly:\n\n"
+            + _PRD_FORMAT,
+            repo_path, allowed_tools=_RECON_ALLOWED_TOOLS,  # read-only
+            github_token=gh_token, resume_session_id=recon_session,
+        )
+        recon_session = prd_res.get("session_id") or recon_session
+        prd = (prd_res.get("result") or "").strip() if prd_res.get("ok") else ""
+        if prd:
+            enriched = (
+                f"{pending.get('user_input') or ''}\n\n---\n\n{_PRD_MARKER}\n\n{prd}"
+            )[:20000]
+            pending["user_input"] = enriched  # shared across repos → reused, not regenerated
+            try:
+                await client.update_task_ml(task_id, {"description": enriched}, model_used=_EPIC_MODELS)
+            except Exception:  # noqa: BLE001 — persisting the PRD is best-effort
+                pass
+
     await send(Envelope(
         type="step_update", thread_id=thread_id,
         data={"status": "running", "current_step": f"Executing locally in {name} (claude_code)"},
@@ -1047,7 +1323,8 @@ async def _code_one_repo(
     # Build the prompt with framing that matches the target: a git repo we manage
     # (branch + PR) vs a plain local folder (BA/analyst deliverables, no git/PR).
     # When recon ran, the implementation resumes that session so its grounded plan
-    # stays in context; the prompt tells the agent to implement THAT plan.
+    # (and the technical PRD, if generated) stays in context; if a PRD is present the
+    # prompt makes it the authoritative spec.
     prompt = _build_local_prompt(
         pending["user_input"], pending.get("structured_plan"),
         pending.get("human_instructions"),
@@ -2555,7 +2832,17 @@ async def handle_orchestrate_auto_local_run(
             if ttype in ("epic", "story"):
                 handler = _handle_epic if ttype == "epic" else _handle_story
                 code = "EPIC_DECOMPOSE_FAILED" if ttype == "epic" else "STORY_HANDLE_FAILED"
+                # Validation gate: Epics are always validated; a Story only when it
+                # is USER-driven (a SYSTEM/bot-created Story is trusted). A rejected
+                # ticket is commented + moved to Backlog inside the gate — skip it.
+                driven_by = str(task.get("drivenBy") or "").strip().upper()
+                needs_validation = (ttype == "epic") or (ttype == "story" and driven_by != "SYSTEM")
                 try:
+                    if needs_validation and not await _validate_ticket_or_reject(
+                        client, task, ttype, payload, send, thread_id
+                    ):
+                        processed += 1
+                        continue
                     await handler(client, task, payload, send, thread_id)
                 except Exception as exc:  # noqa: BLE001
                     logger.warning("auto_local.%s_failed task=%s err=%s", ttype, tid, exc)