@capagents/forgeqe 1.2.1 → 1.3.0

package/py/forgeqe_engine/service.py

@@ -15,6 +15,7 @@ import os
 import re
 import time
 from dataclasses import dataclass, field
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Callable, Dict, List, Optional, Set, Tuple
 
@@ -25,6 +26,7 @@ from .memory import READ_ONLY_ACTIONS, MemoryStore, compact_step, flow_step, pag
 from .prompts import CONVENTIONS, text as prompt_text, use_prompts
 from .report import CASE_REPORT_INSTRUCTION, CaseReport, build_timeline, case_report_from_history
 from .replay import ReplayOutcome, handoff_task, replay_flow
+from .observe import check_key, checkable, checks_for_flow
 from .settings import (
     _truthy_env,
     _browser_use_agent_tuning_kwargs,
@@ -107,6 +109,9 @@ class RunRequest:
     logins: List[Dict[str, Any]] = field(default_factory=list)
     # Number of steps in the test case this goal came from; the agent then reports a verdict for each.
     case_steps: int = 0
+    # The test case and a key per step (changes when the step is reworded): an edited case replays its unchanged steps.
+    case_id: str = ""
+    case_step_keys: List[str] = field(default_factory=list)
     # Step screenshots for the report: "all", "failures", or "off".
     screenshots: str = "all"
     # Accessibility checks on each page visited, for the report.
@@ -139,6 +144,8 @@ class RunRequest:
         return cls(
             logins=[x for x in (d.get("logins") or []) if isinstance(x, dict)],
             case_steps=int(d["case_steps"]) if str(d.get("case_steps") or "").isdigit() else 0,
+            case_id=str(d.get("case_id") or ""),
+            case_step_keys=[str(k) for k in (d.get("case_step_keys") or []) if str(k)],
             screenshots=str(d.get("screenshots") or "all").lower(),
             accessibility=d.get("accessibility") is not False,
             overlay=d.get("overlay") is not False,
@@ -395,6 +402,41 @@ def serialize_browser_step_payload(browser_state: Any, agent_output: Any, n_step
 
 
 REPLAY_MODES = ("verify", "trust", "off")
+# checks_first (docs/COST_ARCHITECTURE.md): every Nth replay of a flow is still checked by the agent, so a check that
+# passes when it should not is caught; and a flow not passed for this long is checked by the agent again.
+CANARY_EVERY = 10
+MAX_FLOW_AGE_DAYS = 30
+
+
+def _int(raw: Any, default: int) -> int:
+    try:
+        n = int(raw)
+    except (TypeError, ValueError):
+        return default
+    return n if n >= 0 else default
+
+
+def judged_by_checks(flow: Dict[str, Any], replay: Any, mem: "MemoryRun") -> Optional[Dict[str, Any]]:
+    """
+    After a complete replay of an exact flow: whether its recorded checks decide the run with no model. ok: every
+    check was found on the page again. Otherwise `why` says what leaves it to the agent (today's verify path).
+    """
+    why = checkable(flow)
+    if why:
+        return {"ok": False, "why": why}
+    if len(replay.checked) < len(flow.get("checks") or []) or not all(c.get("holds_now") for c in replay.checked):
+        return {"ok": False, "why": "not every recorded check was found on the page again"}
+    replays = int(flow.get("replays") or 0) + 1
+    if mem.canary_every and replays % mem.canary_every == 0:
+        return {"ok": False, "why": f"replay {replays} of this flow: every {mem.canary_every}th is checked by the agent too"}
+    last = str(flow.get("last_success") or "")
+    try:
+        age = (datetime.now(timezone.utc) - datetime.fromisoformat(last.replace("Z", "+00:00"))).days if last else None
+    except ValueError:
+        age = None
+    if age is None or age > mem.max_age_days:
+        return {"ok": False, "why": f"the flow last passed more than {mem.max_age_days} days ago" if age is not None else "the flow has no recorded pass"}
+    return {"ok": True, "why": ""}
 
 
 @dataclass
@@ -418,6 +460,59 @@ class MemoryRun:
     used_checkpoint: str = ""
     # Actions that worked without changing the page (dead clicks, read-only scripts): not part of the flow.
     no_effect: List[str] = field(default_factory=list)
+    # The test case this run is for, and a key per case step.
+    case_id: str = ""
+    case_keys: List[str] = field(default_factory=list)
+    # Case step number -> flow steps done when its expected result was recorded (the end of that step).
+    check_at: Dict[int, int] = field(default_factory=dict)
+    # Ends of the case steps a replay already did, carried over from the flow that was replayed.
+    carried_ends: List[Optional[int]] = field(default_factory=list)
+    # registry.mode on (docs/COST_ARCHITECTURE.md): the flow keeps its checks and a replay is judged by them.
+    checks_first: bool = False
+    # The checks the replayed flow had, and those the agent recorded this run with the flow step each came after.
+    flow_checks: List[Dict[str, Any]] = field(default_factory=list)
+    recorded: List[Dict[str, Any]] = field(default_factory=list)
+    check_pos: Dict[str, int] = field(default_factory=dict)
+    check_text: Dict[str, Any] = field(default_factory=dict)
+    canary_every: int = CANARY_EVERY
+    max_age_days: int = MAX_FLOW_AGE_DAYS
+
+    def checks_to_save(self, status: str) -> Optional[List[Dict[str, Any]]]:
+        """The checks the flow keeps after this run; None leaves the flow's as they are."""
+        if not self.checks_first or status != "complete":
+            return None
+        new = checks_for_flow(self.recorded, self.check_pos)
+        if not self.llm_steps:
+            # A replay judged by its checks: the same steps, so the same checks.
+            return list(self.flow_checks) if self.flow_checks else None
+        # Checks from the replayed part still stand where the agent did not record them again.
+        done = len(self.replay.done) if self.replay else 0
+        keys = {check_key(c) for c in new}
+        carried = [c for c in self.flow_checks if 0 < int(c.get("at") or 0) <= done and check_key(c) not in keys]
+        return carried + new
+
+    def note_checks(self, checks: List[Dict[str, Any]]) -> None:
+        """After an agent step: each case step whose check was just recorded ends at the flow as it is now."""
+        self.recorded = checks
+        for c in checks:
+            key = check_key(c)
+            # A check recorded again (the same expected result, new text) moves to where it was recorded last.
+            if key and self.check_text.get(key) != c.get("text"):
+                self.check_pos[key] = len(self.steps)
+                self.check_text[key] = c.get("text")
+        for c in checks:
+            n = c.get("step")
+            if isinstance(n, int) and 0 < n <= len(self.case_keys) and n not in self.check_at:
+                self.check_at[n] = len(self.steps)
+
+    def case_ends(self) -> List[Optional[int]]:
+        ends: List[Optional[int]] = [None] * len(self.case_keys)
+        for i, e in enumerate(self.carried_ends[: len(ends)]):
+            ends[i] = e
+        for n, at in self.check_at.items():
+            if ends[n - 1] is None:
+                ends[n - 1] = at
+        return ends
 
     def checkpoint(self) -> Optional[Dict[str, Any]]:
         """Save the steps that worked so far and the page memory learned so far, so a run cut off here can be picked up."""
@@ -447,7 +542,14 @@ class MemoryRun:
         if not folder:
             return None
         mode = str((req.memory or {}).get("replay") or "verify").lower()
-        return cls(MemoryStore(folder), mode if mode in REPLAY_MODES else "verify", req.goal, start_url)
+        mem = req.memory or {}
+        return cls(
+            MemoryStore(folder), mode if mode in REPLAY_MODES else "verify", req.goal, start_url,
+            case_id=req.case_id, case_keys=list(req.case_step_keys) if req.case_id else [],
+            checks_first=bool(mem.get("checks_first")),
+            canary_every=_int(mem.get("canary_every"), CANARY_EVERY),
+            max_age_days=_int(mem.get("max_age_days"), MAX_FLOW_AGE_DAYS),
+        )
 
     def finish(self, out: Dict[str, Any]) -> Dict[str, Any]:
         self.finished = True
@@ -470,6 +572,8 @@ class MemoryRun:
                 replayed=len(self.replay.done) if self.replay else 0,
                 llm_steps=self.llm_steps,
                 resume=self.resume if status == "fail" else None,
+                case={"id": self.case_id, "keys": self.case_keys, "ends": self.case_ends()} if self.case_id and self.case_keys else None,
+                checks=self.checks_to_save(status),
             )
         except Exception as ex:
             logger.warning("memory: could not save the flow: %s", ex)
@@ -494,6 +598,11 @@ class MemoryRun:
                 info["repaired"] = {"step": self.replay.stopped_at, "reason": self.replay.reason, "agent_steps": self.llm_steps}
         if self.replay and self.replay.heals:
             info["heals"] = self.replay.heals
+        if self.replay and self.replay.checked:
+            info["checked"] = len(self.replay.checked)
+            info["checks_held"] = sum(1 for c in self.replay.checked if c.get("holds_now"))
+        if self.replay and self.replay.skipped_reads:
+            info["skipped_reads"] = self.replay.skipped_reads
         if self.resume and status == "fail":
             info["resume"] = {
                 "steps": len(self.resume["steps"]),
@@ -788,7 +897,7 @@ async def run_browser_task(req: RunRequest, emit: Emit, cancel_event: asyncio.Ev
     except Exception as e:
         return {"success": False, "error": str(e), "summary": ""}
     llm_calls: List[Tuple[float, float]] = []
-    _time_llm_calls(llm, llm_calls)
+    _time_llm_calls(llm, llm_calls, lambda c: emit({"type": "call", **c}))
     use_prompts(req.prompts)
     diag = Diagnostics(accessibility=req.accessibility, network=req.network, axe=req.axe or None, vitals=req.vitals, visual=req.visual)
 
@@ -920,6 +1029,13 @@ async def run_browser_task(req: RunRequest, emit: Emit, cancel_event: asyncio.Ev
                 mem.used_checkpoint = str(checkpoint.get("run_id") or "")
             elif saved and isinstance(saved.get("resume"), dict) and saved["resume"].get("steps"):
                 flow, kind = saved["resume"], "resume"
+            elif mem.case_id and mem.case_keys:
+                # The test case was edited (its goal is new): replay its steps before the first one that changed.
+                earlier = mem.store.load_case_flow(mem.case_id)
+                if earlier and str(earlier.get("start_url") or "") == (normalized_initial or ""):
+                    done, end = MemoryStore.case_prefix(earlier, mem.case_keys)
+                    if done:
+                        flow, kind = {**earlier, "steps": earlier["steps"][:end], "case_steps_done": done}, "prefix"
         if flow and kind and flow.get("steps"):
             if kind == "interrupted":
                 replay_text = (
@@ -932,6 +1048,11 @@ async def run_browser_task(req: RunRequest, emit: Emit, cancel_event: asyncio.Ev
                     + (f" ({flow['run_id']})" if flow.get("run_id") else "")
                     + (f", which went wrong at step {flow['failed_at']}" if flow.get("failed_at") else "")
                 )
+            elif kind == "prefix":
+                replay_text = (
+                    f"The test case changed after step {flow['case_steps_done']}: replaying the {len(flow['steps'])} recorded "
+                    f"steps that did steps 1 to {flow['case_steps_done']}, which did not change"
+                )
             else:
                 replay_text = (
                     f"Replaying {len(flow['steps'])} recorded steps from memory "
@@ -940,13 +1061,19 @@ async def run_browser_task(req: RunRequest, emit: Emit, cancel_event: asyncio.Ev
             emit({"type": "memory", "text": replay_text})
             await browser.start()
             await diag.start(browser)
+            mem.flow_checks = [c for c in (flow.get("checks") or []) if isinstance(c, dict)] if mem.checks_first else []
             replay = await replay_flow(
-                flow, browser=browser, store=mem.store, emit=emit, cancel_event=cancel_event, on_step=lambda: diag.sample(browser), overlay=overlay
+                flow, browser=browser, store=mem.store, emit=emit, cancel_event=cancel_event, on_step=lambda: diag.sample(browser), overlay=overlay,
+                checks_first=mem.checks_first and kind == "exact",
             )
             mem.replay = replay
             for done_step in replay.done:
                 mem.add(done_step)
             replay_offset = replay.emitted
+            if replay.complete and kind in ("exact", "prefix"):
+                # The case steps the replay did end where they ended in the recorded run.
+                known = list(flow.get("case_step_ends") or [])
+                mem.carried_ends = known[: int(flow.get("case_steps_done") or len(known))]
             if replay.complete and kind == "exact":
                 emit({"type": "memory", "text": f"Replayed all {len(replay.done)} steps without the LLM"})
             elif replay.complete:
@@ -958,6 +1085,30 @@ async def run_browser_task(req: RunRequest, emit: Emit, cancel_event: asyncio.Ev
                 out = {"success": False, "error": err, "summary": err, "step_events": collected_steps, "cancelled": True}
                 _save(out, "cancelled")
                 return out
+            judged = judged_by_checks(flow, replay, mem) if replay.complete and kind == "exact" and mem.checks_first and mem.mode == "verify" else None
+            if judged and judged["ok"]:
+                held = replay.checked
+                summary = f"Replayed all {len(replay.done)} recorded steps and found all {len(held)} recorded checks on the page again, without calling the LLM."
+                if flow.get("summary"):
+                    summary += f"\n\nResult of the run that recorded them: {flow['summary']}"
+                emit({"type": "memory", "text": f"All {len(held)} recorded checks hold: passed without the LLM"})
+                out = {
+                    "success": True,
+                    "outcome": "passed",
+                    "summary": summary,
+                    "result_markdown": f"### Task\n\n{goal}\n\n---\n\n## Result\n\n{summary}",
+                    "session_id": req.session_id,
+                    "final_url": replay.url,
+                    "usage": {"input": 0, "output": 0},
+                    "steps": replay.emitted,
+                    "step_events": collected_steps,
+                    "checks": [{k: v for k, v in c.items() if k in ("expected", "text", "url", "step")} for c in held],
+                    "browser": await browser_profile(browser, browser_kw, provider=browser_provider, remote=browser_remote),
+                }
+                _save(out, "memory_checks")
+                return out
+            if judged and not judged["ok"]:
+                emit({"type": "memory", "text": f"The agent checks the result: {judged['why']}"})
             if replay.complete and mem.mode == "trust" and kind == "exact":
                 summary = f"Replayed all {len(replay.done)} recorded steps from memory without calling the LLM."
                 if flow.get("summary"):
@@ -1141,6 +1292,7 @@ async def run_browser_task(req: RunRequest, emit: Emit, cancel_event: asyncio.Ev
                     mem, pending_actions, results, mem.llm_steps, agent_note(getattr(last, "model_output", None)),
                     effects=list(action_effects), page_url=step_url["url"],
                 )
+                mem.note_checks(recorded_checks)
                 try:
                     point = mem.checkpoint()
                     if point:

package/src/capabilities/registry.ts

@@ -111,19 +111,20 @@ export const CAPABILITIES: Capability[] = [
     area: "Test cases",
     title: "Check and improve test cases",
     summary:
-      "Checks test cases before they run (vague or missing expected results, missing test data, placeholders, duplicates) against the story, feature, and epic they test, then rewrites Azure DevOps cases once the user agrees.",
+      "Checks test cases before they run (vague or missing expected results, missing test data, placeholders, duplicates) against the story, feature, and epic they test, then rewrites Azure DevOps or Jira cases in place once the user agrees.",
     tools: ["check_test_cases", "update_test_case"],
     examples: ["Are the cases in test plan 12 good enough to run?", "Fix the expected results of case 4512"],
-    requires: [{ kind: "system", anyOf: ["azure_devops"], optional: true, why: "to rewrite cases in place" }],
+    requires: [{ kind: "system", anyOf: ["azure_devops", "jira"], optional: true, why: "to rewrite cases in place" }],
     docs: [{ doc: "HOW_TO_USE.md", heading: "Checking test cases before they run" }],
   },
   {
     id: "write-test-cases",
     area: "Test cases",
     title: "Write test cases from a story",
-    summary: "Writes test cases from a story's acceptance criteria and saves them in Azure DevOps or Jira, linked to the story.",
-    tools: ["save_test_cases"],
-    examples: ["Write test cases for story 1234 and save them"],
+    summary:
+      "Writes test cases from a story's acceptance criteria and saves them in Azure DevOps or Jira, linked to the story. Reads the cases already linked first, so asking again adds only what is missing and updates cases in place instead of duplicating them; plans end-to-end journeys from the existing cases.",
+    tools: ["story_test_cases", "save_test_cases", "e2e_journey"],
+    examples: ["Write test cases for story 1234 and save them", "Build an end-to-end journey from story 1234's cases"],
     requires: [{ kind: "system", anyOf: ["azure_devops", "jira"] }],
     docs: [{ doc: "HOW_TO_USE.md", heading: "Where cases come from" }],
   },
@@ -185,6 +186,19 @@ export const CAPABILITIES: Capability[] = [
     ],
     docs: [{ doc: "HOW_TO_USE.md", heading: "Finding and running existing tests" }],
   },
+  {
+    id: "regression-packs",
+    area: "Automated tests",
+    title: "Regression packs for a release",
+    summary: "Builds a regression pack from what goes into a release (an Azure DevOps sprint or work items, a commit range, pull requests, or changes read from any connected tool): the tests those changes can break, each with why, plus risk-area and smoke tests, and the changes no test covers. Runs it locally, on TestMu AI, or in a pipeline, and compares each run with the last.",
+    tools: ["build_regression_pack", "run_regression_pack", "list_regression_packs"],
+    examples: ["Build a regression pack for sprint 12 and run it on TestMu", "Which tests should we run for the PRs merged this week?"],
+    requires: [
+      { kind: "input", what: "a repository with tests" },
+      { kind: "system", anyOf: ["azure_devops", "jira"], optional: true, why: "to read a sprint's or release's work items" },
+    ],
+    docs: [{ doc: "HOW_TO_USE.md", heading: "Regression packs for a release" }],
+  },
   {
     id: "flaky-tests",
     area: "Automated tests",

package/src/cases/ado.ts

@@ -192,7 +192,7 @@ const xml = new XMLParser({ ignoreAttributes: false, attributeNamePrefix: "", pr
 type Node = Record<string, unknown> & { ":@"?: Record<string, string> }
 
 /** Microsoft.VSTS.TCM.Steps: `<step>` action/expected pairs in order, with shared steps (`<compref ref>`) inlined. */
-async function parseSteps(source: string, base: string, auth: string, depth = 0): Promise<CaseStep[]> {
+export async function parseSteps(source: string, base: string, auth: string, depth = 0): Promise<CaseStep[]> {
   if (!source.trim()) return []
   const steps: CaseStep[] = []
   const walk = async (nodes: Node[]) => {

package/src/cases/journey.ts

@@ -0,0 +1,61 @@
+import { stepText, type CaseStep } from "./types.ts"
+
+/** A test case as a journey uses it. */
+export type JourneyCase = { id: string; title: string; url?: string; startUrl?: string; steps: CaseStep[] }
+
+/** One case inside a journey: its steps are `from`-`to` of the journey (1-based), after the shared steps. */
+export type JourneySection = { caseId: string; title: string; from: number; to: number; negative: boolean }
+
+export type Journey = { startUrl?: string; shared: CaseStep[]; steps: CaseStep[]; sections: JourneySection[]; saved: number }
+
+/** Steps that look like a negative path: a refusal, an error, or one that ends the session or removes data. */
+const NEGATIVE = /\b(invalid|incorrect|wrong|error|denied|refused|rejects?|rejected|fails?|failed|locked|not allowed|cannot|can't|unauthori[sz]ed|forbidden|sign(?:s|ed)? out|log(?:s|ged)? out|delete[sd]?|remove[sd]?)\b/i
+
+const key = (s: CaseStep) => `${stepText(s.action)}|${stepText(s.expected)}`
+
+function sharedPrefix(cases: JourneyCase[]): number {
+  let n = 0
+  for (;;) {
+    const first = cases[0].steps[n]
+    if (!first || cases.some((c) => !c.steps[n] || key(c.steps[n]) !== key(first))) return n
+    n++
+  }
+}
+
+/**
+ * Journeys from cases that start the same way: same start page and first step. The steps they all share come once,
+ * then each case's own steps follow as a section; cases that look negative go last, since they may end the session.
+ * A case that starts like no other stays on its own. The draft keeps the cases' order otherwise: the agent reorders it.
+ */
+export function planJourneys(cases: JourneyCase[]): { journeys: Journey[]; alone: JourneyCase[]; stepsSaved: number } {
+  const groups = new Map<string, JourneyCase[]>()
+  for (const c of cases) {
+    if (!c.steps.length) continue
+    const g = `${c.startUrl || ""}\n${key(c.steps[0])}`
+    groups.set(g, [...(groups.get(g) || []), c])
+  }
+  const journeys: Journey[] = []
+  const alone: JourneyCase[] = cases.filter((c) => !c.steps.length)
+  for (const group of groups.values()) {
+    if (group.length < 2) {
+      alone.push(...group)
+      continue
+    }
+    const n = sharedPrefix(group)
+    const shared = group[0].steps.slice(0, n)
+    const ordered = group
+      .map((c) => ({ c, tail: c.steps.slice(n) }))
+      .map((x) => ({ ...x, negative: NEGATIVE.test(x.tail.map((s) => `${s.action} ${s.expected || ""}`).join(" ")) }))
+      .sort((a, b) => Number(a.negative) - Number(b.negative))
+    const steps = [...shared]
+    const sections: JourneySection[] = []
+    for (const { c, tail, negative } of ordered) {
+      // A case that is only the shared steps is covered by them.
+      const from = tail.length ? steps.length + 1 : 1
+      steps.push(...tail)
+      sections.push({ caseId: c.id, title: c.title, from, to: tail.length ? steps.length : n, negative })
+    }
+    journeys.push({ startUrl: group[0].startUrl, shared, steps, sections, saved: (group.length - 1) * n })
+  }
+  return { journeys, alone, stepsSaved: journeys.reduce((sum, j) => sum + j.saved, 0) }
+}

package/src/cases/readiness.ts

@@ -20,7 +20,8 @@ import { adoSprints, findSprint } from "./sprints.ts"
  * runs: the newest suite report for the case, then the automated test's history.
  */
 
-export type Scope = { sprint?: string; area?: string; parent?: number; ids?: number[]; project?: string }
+/** iteration: an iteration path and everything under it, such as a release ("Release 2026.09", or Project\Release 2026.09). */
+export type Scope = { sprint?: string; iteration?: string; area?: string; parent?: number; ids?: number[]; project?: string }
 
 export type Outcome = "passed" | "failed" | "blocked" | "not run"
 export type CaseRow = { id: number; title: string; url: string; automated: boolean; test?: string; outcome: Outcome; when?: string; from?: "Azure DevOps" | "ForgeQE"; flaky?: boolean; quarantined?: boolean }
@@ -118,11 +119,26 @@ function forgeqeResults(suitesDir: string): Map<number, { outcome: Outcome; when
   return out
 }
 
-export async function releaseReadiness(cfg: AppConfig, repo: string, scope: Scope, thresholds: ReleaseThresholds = DEFAULT_THRESHOLDS): Promise<Readiness> {
+export type WorkItem = Item
+
+/**
+ * An Azure DevOps scope as work items: a sprint, an area, a parent epic or feature and everything under it, or given
+ * ids. Gives the stories in it, the WIQL filter its other work items share (empty for a parent or ids), and helpers to
+ * query and read more. Release readiness and regression packs both start here.
+ */
+export async function resolveScope(cfg: AppConfig, scope: Scope): Promise<{
+  label: string
+  filter: string
+  project?: string
+  org: string
+  storyIds: number[]
+  wiql: (query: string) => Promise<number[]>
+  items: (ids: number[]) => Promise<Item[]>
+  urlOf: (it: Item) => string
+}> {
   const { org, auth, project: configured } = adoSettings(cfg.sources)
   const project = scope.project || configured
   if (!project && !scope.ids?.length) throw new Error("Name the Azure DevOps project (project, or sources.azure_devops.project) for a sprint, area, or epic.")
-  const notes: string[] = []
   const wiql = async (query: string) => {
     const { data } = await http<{ workItems?: { id: number }[]; workItemRelations?: { target?: { id: number } }[] }>(`${org}/${encodeURIComponent(project!)}/_apis/wit/wiql?api-version=7.1`, { auth, body: { query } })
     return [...new Set([...(data?.workItems || []).map((w) => w.id), ...(data?.workItemRelations || []).map((r) => r.target?.id).filter((n): n is number => Boolean(n))])]
@@ -130,8 +146,9 @@ export async function releaseReadiness(cfg: AppConfig, repo: string, scope: Scop
   const items = async (ids: number[]) => {
     const out: Item[] = []
     for (let i = 0; i < ids.length; i += 200) {
-      const { data } = await http<{ value?: Item[] }>(`${org}/_apis/wit/workitems?ids=${ids.slice(i, i + 200).join(",")}&$expand=relations&api-version=7.1`, { auth })
-      out.push(...(data?.value || []))
+      // errorPolicy=omit: one id that does not exist, or that the token cannot read, does not lose the others.
+      const { data } = await http<{ value?: (Item | null)[] }>(`${org}/_apis/wit/workitems?ids=${ids.slice(i, i + 200).join(",")}&$expand=relations&errorPolicy=omit&api-version=7.1`, { auth })
+      out.push(...(data?.value || []).filter((w): w is Item => Boolean(w)))
     }
     return out
   }
@@ -156,14 +173,26 @@ export async function releaseReadiness(cfg: AppConfig, repo: string, scope: Scop
       parts.push(`[System.IterationPath] UNDER ${q(s.path)}`)
       label = `sprint ${s.name}${s.start ? ` (${s.start} to ${s.end})` : ""}`
     } else label = ""
+    if (scope.iteration) {
+      const iterationPath = scope.iteration.includes("\\") || !project ? scope.iteration : `${project}\\${scope.iteration}`
+      parts.push(`[System.IterationPath] UNDER ${q(iterationPath)}`)
+      label = [label, `iteration ${iterationPath}`].filter(Boolean).join(", ")
+    }
     if (scope.area) {
       parts.push(`[System.AreaPath] UNDER ${q(scope.area)}`)
       label = [label, `area ${scope.area}`].filter(Boolean).join(", ")
     }
-    if (!parts.length) throw new Error("Give a sprint, an area, a parent epic or feature, or work item ids.")
+    if (!parts.length) throw new Error("Give a sprint, an iteration path, an area, a parent epic or feature, or work item ids.")
     filter = parts.join(" AND ")
     storyIds = await wiql(`SELECT [System.Id] FROM WorkItems WHERE [System.TeamProject] = @project AND ${REQUIREMENT} AND [System.State] <> 'Removed' AND ${filter}`)
   }
+  return { label, filter, ...(project ? { project } : {}), org, storyIds, wiql, items, urlOf }
+}
+
+export async function releaseReadiness(cfg: AppConfig, repo: string, scope: Scope, thresholds: ReleaseThresholds = DEFAULT_THRESHOLDS): Promise<Readiness> {
+  const { org, auth } = adoSettings(cfg.sources)
+  const notes: string[] = []
+  const { label, filter, project, storyIds, wiql, items, urlOf } = await resolveScope(cfg, scope)
   const storyItems = await items(storyIds)
 
   // Test cases each story is tested by, and their newest outcome.