devops-bot-sdk 1.4.33__tar.gz → 1.4.35__tar.gz

{devops_bot_sdk-1.4.33 → devops_bot_sdk-1.4.35}/PKG-INFO

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

{devops_bot_sdk-1.4.33 → devops_bot_sdk-1.4.35}/devops_bot_sdk.egg-info/PKG-INFO

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

{devops_bot_sdk-1.4.33 → devops_bot_sdk-1.4.35}/pyproject.toml

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

{devops_bot_sdk-1.4.33 → devops_bot_sdk-1.4.35}/sdk/__init__.py

@@ -1,6 +1,6 @@
 """AgentOS Desktop SDK — thin HTTPS/SSE client for the Electron app.
 
-Version: 1.4.33
+Version: 1.4.35
 
 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.33"
+__version__ = "1.4.35"
 __author__  = "AgentOS"
 
 from sdk.client import BackendClient

{devops_bot_sdk-1.4.33 → devops_bot_sdk-1.4.35}/sdk/client.py

@@ -58,7 +58,7 @@ def _notify_status(task_id: str, status: str) -> None:
             pass
 
 
-SDK_VERSION    = "1.4.33"
+SDK_VERSION    = "1.4.35"
 _POLL_INTERVAL = 3.0
 _POLL_TIMEOUT  = 600.0
 _ORCHESTRATE_TIMEOUT      = 2700.0  # 45 min — covers approval wait + VPS execution time

{devops_bot_sdk-1.4.33 → devops_bot_sdk-1.4.35}/sdk/config.py

@@ -122,6 +122,22 @@ def get_base_url() -> str:
     return load().get("base_url", AI_DEFAULT_URL)
 
 
+def get_branch_name_template() -> str | None:
+    """Org-wide branch-naming convention, if configured in config.toml.
+
+    Lets teams enforce a house convention without repeating it in every ticket's
+    humanInstructions. Supports the ``{jira_key}`` placeholder, e.g.::
+
+        branch_name_template = "{jira_key}"        # branch named exactly the ticket id
+        branch_name_template = "feature/{jira_key}"
+
+    A per-ticket directive parsed from humanInstructions always wins over this.
+    Returns None when unset (SDK falls back to feature/<key>-<slug>).
+    """
+    val = _load_raw().get("branch_name_template")
+    return val.strip() if val and val.strip() else None
+
+
 def get_token() -> str:
     """Return the stored apiTokenHash. Raises TokenNotConfigured if missing."""
     cfg = load()

{devops_bot_sdk-1.4.33 → devops_bot_sdk-1.4.35}/sdk/git_ops.py

@@ -148,8 +148,17 @@ async def start_branch(
     summary: str | None,
     github_token: str | None,
     base: str | None = None,
+    branch_name: str | None = None,
 ) -> dict | None:
-    """Create + check out `feature/<jira_key>-<slug>` off the resolved base.
+    """Create + check out a feature branch off the resolved base.
+
+    Branch name:
+      - `branch_name` given (an explicit name parsed from the Jira
+        humanInstructions or a configured template, e.g. the exact ticket id
+        "CD-72") → used VERBATIM. This is how "name the branch exactly
+        <TICKET-ID>" is honoured — the SDK owns branching for the managed repo,
+        so the convention has to be applied here, not by the agent.
+      - omitted → the historical default `feature/<jira_key>-<slug>`.
 
     Base resolution (per repo):
       - `base` given (named in the Jira humanInstructions, possibly per-repo) →
@@ -171,8 +180,13 @@ async def start_branch(
     if not await _is_git_repo(path, env):
         return None
 
-    key = slugify(jira_key or "task", max_len=24)
-    branch = f"feature/{key}-{slugify(summary)}"
+    explicit_name = (branch_name or "").strip().lstrip("/")
+    if explicit_name:
+        # Honour the exact name the human/convention asked for (e.g. "CD-72").
+        branch = explicit_name
+    else:
+        key = slugify(jira_key or "task", max_len=24)
+        branch = f"feature/{key}-{slugify(summary)}"
     # Fetch so any remote base ref (origin/HEAD, origin/<base>) is present/fresh.
     await _run(["git", "fetch", "origin"], path, env, timeout=180.0)
 
@@ -292,8 +306,13 @@ async def finish_pr(
     env = _git_env(github_token)
 
     await _run(["git", "add", "-A"], path, env)
-    # commit — no-op (non-zero) when there's nothing staged; ignore that case.
-    await _run(["git", "commit", "-m", title], path, env)
+    # commit — returns non-zero when there's nothing staged. Capture that: a
+    # zero exit means a real commit was created (the agent actually changed
+    # something), which the caller uses as the authoritative "did work happen?"
+    # signal — far more reliable than files_changed, which also counts files the
+    # agent merely READ.
+    commit_rc, _, _ = await _run(["git", "commit", "-m", title], path, env)
+    committed = commit_rc == 0
 
     rc, _, push_err = await _run(
         ["git", "push", "-u", "origin", branch, "--force-with-lease"],
@@ -302,7 +321,8 @@ async def finish_pr(
     pushed = rc == 0
     if not pushed:
         logger.warning("git_ops.push_failed branch=%s error=%s", branch, push_err[:300])
-        return {"pushed": False, "pr_url": None, "pr_error": f"push failed: {push_err[:200]}"}
+        return {"pushed": False, "pr_url": None, "committed": committed,
+                "pr_error": f"push failed: {push_err[:200]}"}
 
     pr_url: str | None = None
     pr_error: str | None = None
@@ -347,4 +367,4 @@ async def finish_pr(
             pr_error = "no PR created"
         logger.warning("git_ops.no_pr branch=%s reason=%s", branch, pr_error)
 
-    return {"pushed": pushed, "pr_url": pr_url, "pr_error": pr_error}
+    return {"pushed": pushed, "pr_url": pr_url, "pr_error": pr_error, "committed": committed}

{devops_bot_sdk-1.4.33 → devops_bot_sdk-1.4.35}/sdk/ipc/handlers.py

@@ -154,6 +154,9 @@ def _build_local_prompt(
     human_instructions: str | None = None,
     agent_mode: bool = True,
     git_managed: bool = True,
+    repo_name: str | None = None,
+    grounded: bool = False,
+    branch_convention: str | None = None,
 ) -> str:
     """Compose the coding prompt for the local claude CLI from the server plan.
 
@@ -173,6 +176,25 @@ def _build_local_prompt(
     locally itself.
     """
     parts: list[str] = []
+    # 0. Per-repo scope + grounding framing — keeps a multi-repo ticket from
+    #    bleeding one repo's work into another, and points the agent at the
+    #    grounded plan it just produced during the read-only recon pass.
+    if repo_name:
+        scope_line = (
+            f"You are working ONLY in the `{repo_name}` repository. Make changes "
+            f"here that belong to THIS repo; do not attempt work that belongs to a "
+            f"different repository."
+        )
+        if grounded:
+            scope_line += (
+                " You have just completed a READ-ONLY exploration of this repo in "
+                "this same session and produced a SCOPE / FILES / PATTERNS / PLAN "
+                "report. Implement THAT grounded plan now — edit the real files you "
+                "identified and follow the existing patterns you found. The server "
+                "plan below is secondary reference; if it conflicts with what the "
+                "code actually is, trust the code and the operator instructions."
+            )
+        parts.append(scope_line)
     # 1. Operator instructions — FIRST, verbatim, authoritative.
     if human_instructions and human_instructions.strip():
         parts.append(
@@ -219,6 +241,12 @@ def _build_local_prompt(
             "out, and the system will commit, push, and open the PR after you finish — "
             "so do NOT create branches, commit, push, or open a PR for the current repo. "
             "(You may still clone and open PRs for OTHER repositories the instructions name.)"
+            + (
+                f"\nFor any OTHER repository you clone yourself, follow the branch-naming "
+                f"convention exactly: name the branch `{branch_convention}` "
+                f"(or the equivalent per that repo's ticket id)."
+                if branch_convention else ""
+            )
         )
     else:
         # Plain local working folder (no GitHub repo / not under our git control) —
@@ -239,6 +267,90 @@ def _build_local_prompt(
     return "\n\n".join(p for p in parts if p)
 
 
+# Read-only tool set for the recon pass — no Write/Edit/Bash, so it physically
+# cannot modify the repo or run git while it explores and plans.
+_RECON_ALLOWED_TOOLS = ["Read", "Glob", "Grep"]
+
+
+def _build_recon_prompt(
+    repo_name: str,
+    user_input: str | None,
+    structured_plan: dict | None,
+    human_instructions: str | None,
+) -> str:
+    """Prompt for the read-only recon pass: explore THIS repo, decide scope, and
+    produce a codebase-grounded plan. The server plan is passed as HINTS only —
+    the whole point is to replace guessed files/contracts with real ones.
+    """
+    parts: list[str] = [
+        f"READ-ONLY RECON PASS for the `{repo_name}` repository. Do NOT create, "
+        "edit, or delete ANY file, and do NOT run git — this pass ONLY explores "
+        "and produces a grounded plan. Implementation happens in the next step.",
+    ]
+    if human_instructions and human_instructions.strip():
+        parts.append(
+            "=== Operator instructions (Jira humanInstructions) — AUTHORITATIVE ===\n"
+            + human_instructions.strip()
+        )
+    sp = structured_plan or {}
+    criteria = sp.get("acceptance_criteria") or []
+    steps = sp.get("task_steps") or []
+    if criteria:
+        parts.append(
+            "Acceptance criteria (server plan — HINTS to verify against the real "
+            "code, not ground truth):\n" + "\n".join(f"- {c}" for c in criteria)
+        )
+    if steps:
+        lines = [
+            f"- {s.get('title', '')}: {s.get('description', '')}".rstrip(": ")
+            for s in steps if isinstance(s, dict)
+        ]
+        if lines:
+            parts.append("Proposed steps (hints):\n" + "\n".join(lines))
+    if user_input and user_input.strip():
+        parts.append(
+            "=== Task description (reference) ===\n" + _clip_text(user_input.strip())
+        )
+    parts.append(
+        "Explore THIS repository to ground the work in what actually exists:\n"
+        "- If a CLAUDE.md is present, read it FIRST and follow its documented "
+        "structure, conventions and commands.\n"
+        "- Prefer graphify (the /graphify skill / graph queries) over reading whole "
+        "files, so this stays fast and cheap on large repos.\n"
+        "- Use Read/Glob/Grep to confirm the REAL files, modules, routes/endpoints, "
+        "request/response shapes, naming and error/test patterns involved.\n\n"
+        "Then output a report with these EXACT sections (and nothing that edits code):\n"
+        "SCOPE: IN   — if this repo genuinely needs changes for this ticket\n"
+        "SCOPE: OUT  — if NOTHING in this repo is in scope (the work belongs to a "
+        "different repo). Be honest — guessing IN and then changing nothing is a failure.\n"
+        "FILES: the actual files you will change (existing paths), or new files with "
+        "their correct location following this repo's real layout\n"
+        "PATTERNS: the existing conventions/contracts to follow (API shape, naming, "
+        "error handling, tests) — cite real examples you found\n"
+        "PLAN: a concrete, ordered implementation plan for THIS repo that references "
+        "the real files and patterns above"
+    )
+    return "\n\n".join(p for p in parts if p)
+
+
+def _parse_scope(recon_text: str | None) -> str:
+    """'out' when recon explicitly declared the repo out of scope, else 'in'.
+
+    Defaults to 'in' on any ambiguity or recon failure so we never REGRESS to the
+    old silent-skip behaviour — a wrongly-included repo is still caught later by
+    the 'in-scope but 0 changes' compliance check.
+    """
+    if not recon_text:
+        return "in"
+    low = recon_text.lower()
+    verdicts = re.findall(r"scope\s*[:=]\s*(in|out)\b", low)
+    if verdicts:
+        return "out" if verdicts[-1] == "out" else "in"
+    if "out-of-scope" in low or "out of scope" in low:
+        return "out"
+    return "in"
+
+
 async def _run_local_pipeline(
     client: BackendClient, payload: dict, send: Callable
 ) -> None:
@@ -448,7 +560,10 @@ async def _code_one_repo(
     name = Path(repo_path).name
 
     # 0. Make sure the repo is present (clone from repo_url only if missing/empty).
-    await git_ops.ensure_repo(repo_path, repo_url, gh_token)
+    #    `is_git` tells coding targets (real git repos → recon + branch + PR) apart
+    #    from plain working folders (documentation / BA deliverables → no recon-
+    #    scope gate, no branch/PR), so non-coding tasks aren't wrongly skipped.
+    is_git = await git_ops.ensure_repo(repo_path, repo_url, gh_token)
 
     _write_count = 0
 
@@ -490,13 +605,80 @@ async def _code_one_repo(
     except Exception:  # noqa: BLE001
         pass
 
-    # 2. feature branch off the resolved base (explicit base from instructions,
-    #    else the repo's current checked-out branch — see git_ops.start_branch).
+    # 2. RECON (read-only): before touching anything, explore THIS repo and
+    #    decide scope + a grounded plan. Skipped on a resume (rate-limit/context
+    #    retry) — the session already holds that context, so we go straight back
+    #    to implementing instead of re-exploring and re-spending tokens.
+    #    Recon is for CODE repos (there's a codebase to ground against + a scope
+    #    decision to make). A plain working folder (documentation / analyst
+    #    deliverables) has no codebase to explore and is never "out of scope", so
+    #    it skips recon and goes straight to producing its deliverables.
+    recon_session: str | None = None
+    scope = "in"
+    recon: dict = {}
+    if not resume_session_id and is_git:
+        await send(Envelope(
+            type="step_update", thread_id=thread_id,
+            data={"status": "running",
+                  "current_step": f"[{name}] Recon — exploring the repo to ground the plan"},
+        ).model_dump())
+        recon = await local_exec.run_claude_local(
+            _build_recon_prompt(
+                name, pending["user_input"], pending.get("structured_plan"),
+                pending.get("human_instructions"),
+            ),
+            repo_path, on_event=_on_event, github_token=gh_token,
+            allowed_tools=_RECON_ALLOWED_TOOLS,  # read-only: no Write/Edit/Bash
+        )
+        recon_session = recon.get("session_id")
+        # A usage-limit hit during recon must be surfaced so the loop waits/retries
+        # rather than treating the repo as done — return it straight up.
+        if recon.get("limit_exceeded"):
+            return {"repo": repo_path, "result": recon, "pr": None,
+                    "branch": None, "scope": "in", "compliance": {"issues": []}}
+        if recon.get("ok"):
+            scope = _parse_scope(recon.get("result"))
+        else:
+            # Recon errored (not a limit) → don't sink the ticket: fall back to the
+            # (ungrounded) server plan and let implementation proceed.
+            await send(Envelope(
+                type="step_update", thread_id=thread_id,
+                data={"status": "running",
+                      "current_step": f"[{name}] Recon unavailable "
+                                      f"({(recon.get('error') or '')[:80]}) — proceeding on the server plan"},
+            ).model_dump())
+
+    if scope == "out":
+        # Honest "nothing here" — no branch, no PR, no empty commit. Reported as a
+        # deliberate no-op (NOT a silent skip, NOT a failure).
+        await send(Envelope(
+            type="step_update", thread_id=thread_id,
+            data={"status": "running",
+                  "current_step": f"[{name}] Out of scope — recon found no work for this ticket here"},
+        ).model_dump())
+        return {
+            "repo": repo_path,
+            "result": {
+                "ok": True,
+                "result": f"OUT_OF_SCOPE — recon found no work for this ticket in {name}.",
+                "files_changed": [],
+                "input_tokens": recon.get("input_tokens", 0),
+                "output_tokens": recon.get("output_tokens", 0),
+                "total_tokens": recon.get("total_tokens", 0),
+                "cost_usd": recon.get("cost_usd", 0.0),
+                "session_id": recon_session,
+            },
+            "pr": None, "branch": None, "scope": "out", "compliance": {"issues": []},
+        }
+
+    # 3. feature branch off the resolved base — named per the human/convention
+    #    directive when given (e.g. exactly "CD-72"), else feature/<key>-<slug>.
+    branch_name = _resolve_branch_name(pending.get("human_instructions"), pending.get("jira_key"))
     branch_info = None
     try:
         branch_info = await git_ops.start_branch(
             repo_path, pending.get("jira_key"), pending.get("summary"), gh_token,
-            base=base,
+            base=base, branch_name=branch_name,
         )
         if branch_info:
             await send(Envelope(
@@ -514,18 +696,22 @@ 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.
     prompt = _build_local_prompt(
         pending["user_input"], pending.get("structured_plan"),
         pending.get("human_instructions"),
         agent_mode=agent_mode, git_managed=bool(branch_info),
+        repo_name=name, grounded=bool(recon_session), branch_convention=branch_name,
     )
 
-    # 3. initial claude run (resume_session_id is set on rate-limit retries so
-    # the model picks up exactly where it was interrupted, skipping re-work).
+    # 3b. initial claude run. resume_session_id (rate-limit/context retry) wins;
+    # otherwise resume the recon session so implementation builds on the recon
+    # exploration instead of starting cold.
     result = await local_exec.run_claude_local(
         prompt, repo_path, on_event=_on_event,
         github_token=gh_token, approval_dir=approval_dir,
-        resume_session_id=resume_session_id or None,
+        resume_session_id=resume_session_id or recon_session or None,
     )
 
     # 4. context-window recovery
@@ -645,6 +831,71 @@ async def _code_one_repo(
             )
             session_id = result.get("session_id") or session_id
 
+    # 5b. SELF-REPAIR loop (diagnose → resume → retry). The recovery loops above
+    #     handle the KNOWN, self-describing failures (context overflow, output
+    #     cap, usage limit). This loop handles everything else — a build that
+    #     won't compile, a failing test, a tool error, or a run that finished OK
+    #     but produced NOTHING. Instead of dropping the ticket to Backlog, we
+    #     resume the SAME session and ask the agent to first DIAGNOSE the root
+    #     cause, then fix and finish. Bounded by _MAX_REPAIR_ATTEMPTS so it can
+    #     never loop forever / burn tokens indefinitely; limit/context/cap errors
+    #     are excluded so their dedicated handlers own them.
+    repair = 0
+    while session_id and repair < _MAX_REPAIR_ATTEMPTS \
+            and not result.get("limit_exceeded") \
+            and not result.get("context_exceeded") \
+            and not result.get("output_cap_exceeded"):
+        errored = not result.get("ok")
+        # "did real work happen?" — actual Write/Edit count, not files merely read.
+        empty = result.get("ok") and _write_count == 0
+        if not (errored or empty):
+            break
+        repair += 1
+        if errored:
+            await send(Envelope(
+                type="step_update", thread_id=thread_id,
+                data={"status": "running",
+                      "current_step": f"[{name}] Error — diagnosing & repairing "
+                                      f"(attempt {repair}/{_MAX_REPAIR_ATTEMPTS})"},
+            ).model_dump())
+            try:
+                await client.log_activity(
+                    f"Task {task_id} [{name}]: run errored — auto-diagnosing "
+                    f"(attempt {repair}): {(result.get('error') or '')[:160]}"
+                )
+            except Exception:  # noqa: BLE001
+                pass
+            repair_prompt = (
+                "Your previous attempt ended with an ERROR:\n\n"
+                f"{(result.get('error') or result.get('result') or 'unknown error')[:1500]}\n\n"
+                "Do NOT start over. First DIAGNOSE the root cause: re-read the relevant "
+                "files, re-run the failing command to see its ACTUAL output, and check "
+                "any logs. State the cause in one line, then FIX it and continue until "
+                "the task is complete and verified. If the same command keeps failing, "
+                "try a different approach rather than repeating it."
+            )
+        else:  # empty — ran clean but wrote nothing
+            await send(Envelope(
+                type="step_update", thread_id=thread_id,
+                data={"status": "running",
+                      "current_step": f"[{name}] Finished with no changes — re-checking scope "
+                                      f"(attempt {repair}/{_MAX_REPAIR_ATTEMPTS})"},
+            ).model_dump())
+            repair_prompt = (
+                "You finished WITHOUT creating or editing any files, but this task is "
+                "expected to produce concrete changes/deliverables. Re-read the operator "
+                "instructions and the plan you produced, and implement the actual work now "
+                "(edit or create the real files). If — and only if — you are certain "
+                "nothing belongs in this location, reply with a single line explaining "
+                "precisely why, and make no changes."
+            )
+        result = await local_exec.run_claude_local(
+            repair_prompt, repo_path, on_event=_on_event,
+            github_token=gh_token, resume_session_id=session_id,
+            approval_dir=approval_dir,
+        )
+        session_id = result.get("session_id") or session_id
+
     # 6. commit + push + PR for THIS repo
     pr = None
     if branch_info and result.get("ok"):
@@ -671,8 +922,39 @@ async def _code_one_repo(
         except Exception as exc:  # noqa: BLE001
             logger.warning("local_run.finish_pr_failed", error=str(exc))
 
+    # 7. Compliance verification (enforce + verify). An in-scope repo that ran OK
+    #    but changed nothing, or that failed to push / open a PR, is NOT "done" —
+    #    these become issues the caller turns into a loud failure, never a silent
+    #    success. (Branch NAME is compliant by construction: the SDK created it
+    #    from the resolved convention above.)
+    issues: list[str] = []
+    if result.get("ok"):
+        if branch_info:
+            # CODE repo: `committed` from finish_pr is authoritative (true only when
+            # a real commit was created); files_changed is a weak fallback.
+            made_output = pr.get("committed") if pr else bool(result.get("files_changed"))
+            if not made_output:
+                issues.append("in scope but produced 0 committed changes")
+            elif not pr.get("pushed"):
+                issues.append("branch was not pushed")
+            elif not pr.get("pr_url"):
+                issues.append(f"no PR opened ({(pr or {}).get('pr_error') or 'unknown'})")
+        else:
+            # Plain working folder (documentation / analyst deliverables, non-git):
+            # no branch/PR to verify, but it must still have PRODUCED something.
+            if _write_count == 0:
+                issues.append("task produced no files/deliverables")
+    if issues:
+        await send(Envelope(
+            type="step_update", thread_id=thread_id,
+            data={"status": "running",
+                  "current_step": f"[{name}] Compliance issue(s): " + "; ".join(issues)},
+        ).model_dump())
+
     return {"repo": repo_path, "result": result, "pr": pr,
-            "branch": (branch_info or {}).get("branch")}
+            "branch": (branch_info or {}).get("branch"), "scope": scope,
+            "compliance": {"issues": issues, "expected_branch": branch_name,
+                           "branch": (branch_info or {}).get("branch")}}
 
 
 async def handle_pipeline_approve(
@@ -776,7 +1058,17 @@ async def handle_pipeline_approve(
         _shutil.rmtree(approval_dir, ignore_errors=True)
 
     # ── Aggregate the per-repo runs for the server finalize + done payload ──
-    ok_any = any(r["result"].get("ok") for r in runs)
+    # Scope-aware: OUT-OF-SCOPE repos (recon found no work there) are deliberate
+    # no-ops, not successes to brag about nor failures to punish. Only IN-SCOPE
+    # repos decide whether the ticket is actually done, and each must be both
+    # ok AND compliant (pushed, PR opened, non-empty) — enforce + verify.
+    scoped = [r for r in runs if r.get("scope", "in") != "out"]
+    out_of_scope = [r for r in runs if r.get("scope") == "out"]
+    noncompliant = [
+        r for r in scoped
+        if (not r["result"].get("ok")) or r.get("compliance", {}).get("issues")
+    ]
+    ok_any = any(r["result"].get("ok") for r in scoped)
     parts: list[str] = []
     pr_urls: list[str] = []
     files_changed: list[str] = []
@@ -828,24 +1120,48 @@ async def handle_pipeline_approve(
             "repo_resume_sessions": repo_resume_sessions,
         }
 
-    # ── Notify on WhatsApp if nothing succeeded ──────────────────────────
-    if not ok_any:
-        err = "; ".join(str(r["result"].get("error") or "unknown") for r in runs) or "no repos processed"
+    # ── Fail loud unless EVERY in-scope repo succeeded AND is compliant ──────
+    # This is the enforce-side of the fix: a repo that ran but changed nothing,
+    # didn't push, or skipped its PR no longer slips through as "done"; and a
+    # ticket whose named repos ALL came back out of scope is escalated for human
+    # review rather than silently closed.
+    if not scoped or noncompliant:
+        if not scoped:
+            named = ", ".join(Path(r["repo"]).name for r in runs) or "the named repo(s)"
+            err = (f"recon found no in-scope work in {named} — nothing was implemented; "
+                   "needs human review (wrong repo/path, or the work belongs elsewhere)")
+        else:
+            def _why(r: dict) -> str:
+                res = r["result"]
+                reason = (res.get("error")
+                          or "; ".join(r.get("compliance", {}).get("issues", []))
+                          or "failed")
+                return f"{Path(r['repo']).name}: {reason}"
+            err = "incomplete / non-compliant — " + " | ".join(_why(r) for r in noncompliant)
         note = (f"⚠ Task {task_id}: context window exceeded — split the ticket or narrow scope."
                 if _is_context_window_error(err)
-                else f"⚠ Task {task_id}: local execution failed — {err[:200]}")
+                else f"⚠ Task {task_id}: {err[:220]}")
         try:
             await client.notify_whatsapp(task_id, note, summary="AgentOS local run alert")
         except Exception:  # noqa: BLE001
             pass
-        await client.log_activity(f"Task {task_id}: local execution failed — {err[:300]}")
+        await client.log_activity(f"Task {task_id}: {err[:300]}")
         await client.move_to_backlog(task_id)
         await send(Envelope(
             type=Envelope.TYPE_ERROR, thread_id=thread_id,
-            data={"code": "LOCAL_EXEC_FAILED", "message": err[:300], "task_id": task_id},
+            data={"code": "LOCAL_EXEC_INCOMPLETE", "message": err[:300], "task_id": task_id},
         ).model_dump())
         return
 
+    # Surface deliberate no-ops so a skipped repo is transparent, not invisible.
+    if out_of_scope:
+        skipped = ", ".join(Path(r["repo"]).name for r in out_of_scope)
+        await send(Envelope(
+            type="step_update", thread_id=thread_id,
+            data={"status": "running",
+                  "current_step": f"Out of scope (no changes): {skipped}"},
+        ).model_dump())
+
     # ── Finalize on the server once per task (validation + Jira/cost) ─────
     await send(Envelope(
         type="step_update", thread_id=thread_id,
@@ -1499,6 +1815,84 @@ def _resolve_base_for(name: str, url: str | None,
     return global_base
 
 
+# Explicit branch-NAME directives (distinct from the base branch you branch
+# FROM). The SDK — not the agent — owns branching for the managed repo, so a
+# convention like "name the branch exactly the ticket id" MUST be applied here.
+_BRANCH_TICKET_RE = _re.compile(
+    r"branch\b[^.\n]{0,60}?\b(?:jira[\s\-]?)?(?:ticket|jira|story|issue)"
+    r"[\s\-]?(?:id|key|number|name|no\.?)\b",
+    _re.I,
+)
+_BRANCH_LITERAL_RES = [
+    _re.compile(
+        r"(?:name|call|create|use)\s+(?:the\s+)?branch\s+"
+        r"(?:named\s+|called\s+|exactly\s+|as\s+)?[\"'`]?([A-Za-z0-9][\w.\-/]*)[\"'`]?",
+        _re.I,
+    ),
+    _re.compile(
+        r"branch\s*(?:name)?\s*(?:should\s+be|must\s+be|has\s+to\s+be|is|=|:)\s*"
+        r"[\"'`]?([A-Za-z0-9][\w.\-/]*)[\"'`]?",
+        _re.I,
+    ),
+]
+# Never a real branch name — filters false positives from the loose patterns.
+_BRANCH_NAME_NOISE = {
+    "the", "a", "an", "exactly", "named", "called", "from", "off", "of",
+    "your", "this", "that", "new", "same", "current", "default", "please",
+    "name", "id", "key", "number", "ticket", "jira", "feature", "should", "must",
+}
+
+
+def _extract_branch_name(text: str | None, jira_key: str | None) -> str | None:
+    """An explicit branch NAME directive from humanInstructions, or None.
+
+    Two shapes are recognised:
+      - a convention referring to the ticket id ("name the branch exactly the
+        JIRA ticket id") → resolves to ``jira_key``.
+      - a literal name ("branch: CD-72", "name the branch release-1").
+    Base-branch directives ("branch from main") are deliberately NOT matched —
+    _extract_base_branches owns those.
+    """
+    if not text:
+        return None
+    if jira_key and _BRANCH_TICKET_RE.search(text):
+        return jira_key
+    for rx in _BRANCH_LITERAL_RES:
+        for m in rx.finditer(text):
+            cand = (m.group(1) or "").strip().strip("./")
+            low = cand.lower()
+            if not cand or low in _BRANCH_NAME_NOISE:
+                continue
+            # "branch: main" alongside "branch from main" is a base, not a name.
+            if low in ("main", "master", "develop", "dev") and "branch from" in text.lower():
+                continue
+            return cand
+    return None
+
+
+def _resolve_branch_name(text: str | None, jira_key: str | None) -> str | None:
+    """Final branch name: per-ticket directive → configured template → None.
+
+    None means "use the SDK default" (feature/<key>-<slug>). A per-ticket
+    directive always beats the org-wide ``branch_name_template`` in config.
+    """
+    explicit = _extract_branch_name(text, jira_key)
+    if explicit:
+        return explicit
+    try:
+        from sdk import config
+        tmpl = config.get_branch_name_template()
+    except Exception:  # noqa: BLE001
+        tmpl = None
+    if tmpl:
+        try:
+            resolved = tmpl.format(jira_key=jira_key or "", key=jira_key or "").strip()
+            return resolved or None
+        except Exception:  # noqa: BLE001
+            return tmpl
+    return None
+
+
 def _extract_repo_targets(text: str | None) -> list[dict]:
     """All repo work-targets named in `text`: ``[{"path", "url", "base"}]``.
 
@@ -1607,6 +2001,10 @@ _MAX_CONTEXT_RESUMES = 3
 _MAX_OUTPUT_CAP_RESUMES = 3
 # Max mid-run crucial-decision approval gates per ticket (safety bound).
 _MAX_CRUCIAL_GATES = 10
+# Max diagnose-and-retry (self-repair) passes per repo for a generic error or an
+# empty (ran-clean-but-changed-nothing) result — distinct from context/cap/limit,
+# which have their own handlers. Bounded so a stuck task can't burn tokens forever.
+_MAX_REPAIR_ATTEMPTS = int(os.getenv("AGENTOS_MAX_REPAIR_ATTEMPTS", "") or 2)
 # Max times a ticket is retried after hitting the Claude usage limit.
 _MAX_LIMIT_RETRIES = 3
 # Cap on how long we'll sleep waiting for a usage-limit window to reset.