@capagents/forgeqe 1.2.1 → 1.3.1

package/src/capabilities/registry.ts

@@ -53,6 +53,13 @@ export type Capability = {
   /** What it does not do, so the agent never promises it. */
   limits?: string[]
   docs: DocRef[]
+  /**
+   * The sections of brain.md (### headings) this capability owns: they leave the system prompt and come on demand, with
+   * `when` in the index of playbooks that stays in it. A section no capability owns stays in the system prompt.
+   */
+  playbook?: { heading: string; when: string }[]
+  /** Tools of other capabilities whose first result also carries this capability's playbook. */
+  alsoAfter?: string[]
 }
 
 export const CAPABILITIES: Capability[] = [
@@ -111,21 +118,26 @@ 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" }],
+    playbook: [
+      { heading: "Testing from requirements", when: "write test cases from a story, a Confluence page, or a specification" },
+      { heading: "End-to-end journeys from test cases", when: "an end-to-end case or flow from test cases that exist" },
+    ],
   },
   {
     id: "domain-compliance",
@@ -149,6 +161,7 @@ export const CAPABILITIES: Capability[] = [
     examples: ["Explore story 1234 and find bugs", "Test this feature beyond the test cases"],
     requires: [{ kind: "live_model" }, { kind: "system", anyOf: ["azure_devops", "jira"], optional: true, why: "to read the story and file bugs" }],
     docs: [{ doc: "HOW_TO_USE.md", heading: "Exploratory testing from a story" }],
+    playbook: [{ heading: "Exploratory testing", when: "explore a story or feature past its scripted cases, or find bugs in it" }],
   },
   {
     id: "write-tests",
@@ -160,6 +173,8 @@ export const CAPABILITIES: Capability[] = [
     examples: ["Write a Playwright test for that run in ../app"],
     requires: [{ kind: "coding_agent" }, { kind: "input", what: "a repository to write the test in (default: the working directory)" }],
     docs: [{ doc: "HOW_TO_USE.md", heading: "6. Tests" }],
+    playbook: [{ heading: "Writing tests", when: "write an automated test from a run, or a session where passed runs become tests" }],
+    alsoAfter: ["browser_run", "run_test_cases"],
   },
   {
     id: "heal-tests",
@@ -170,6 +185,7 @@ export const CAPABILITIES: Capability[] = [
     examples: ["Heal the failing tests in ../app"],
     requires: [{ kind: "coding_agent" }, { kind: "input", what: "a repository with tests" }],
     docs: [{ doc: "HOW_TO_USE.md", heading: "Fixing broken tests" }],
+    playbook: [{ heading: "Repairing broken tests", when: "automated tests that fail, broke after a release, or need healing" }],
   },
   {
     id: "find-run-tests",
@@ -184,6 +200,21 @@ export const CAPABILITIES: Capability[] = [
       { kind: "system", anyOf: ["azure_devops", "jira"], optional: true, why: "to pick tests by sprint" },
     ],
     docs: [{ doc: "HOW_TO_USE.md", heading: "Finding and running existing tests" }],
+    playbook: [{ heading: "Repository tests", when: "find, list, or run the automated tests of the repository" }],
+  },
+  {
+    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" }],
+    playbook: [{ heading: "Regression packs", when: "a regression pack, or which tests to run for a release, sprint, or pull requests" }],
   },
   {
     id: "flaky-tests",
@@ -208,6 +239,8 @@ export const CAPABILITIES: Capability[] = [
       { kind: "either", of: [{ kind: "system", anyOf: ["azure_devops"], why: "for Azure DevOps pull requests" }, { kind: "command", command: "gh", why: "for GitHub pull requests" }] },
     ],
     docs: [{ doc: "HOW_TO_USE.md", heading: "Reviewing pull requests" }],
+    playbook: [{ heading: "Pull requests", when: "review a pull request, its impact, or the tests it can break" }],
+    alsoAfter: ["analyze_pr_impact", "select_pr_tests", "post_pr_test_results", "comment_on_pr"],
   },
   {
     id: "pr-impact",
@@ -240,6 +273,7 @@ export const CAPABILITIES: Capability[] = [
       { doc: "HOW_TO_USE.md", heading: "API and contract tests" },
       { doc: "HOW_TO_USE.md", heading: "End-to-end API scenarios" },
     ],
+    playbook: [{ heading: "API testing", when: "API contracts, API tests, or end-to-end API scenarios (REST, GraphQL, SOAP, gRPC)" }],
   },
   {
     id: "accessibility-performance",
@@ -251,6 +285,8 @@ export const CAPABILITIES: Capability[] = [
     requires: [{ kind: "input", what: "a browser run (from browser_run or run_test_cases); new runs need a live model" }],
     limits: ["Per-page Core Web Vitals, not load testing under many users."],
     docs: [{ doc: "HOW_TO_USE.md", heading: "Accessibility and performance budgets" }],
+    playbook: [{ heading: "Accessibility, performance, and visual changes", when: "accessibility, Core Web Vitals, performance budgets, or visual changes of pages" }],
+    alsoAfter: ["visual_compare", "visual_approve"],
   },
   {
     id: "visual-comparison",
@@ -299,6 +335,7 @@ export const CAPABILITIES: Capability[] = [
     examples: ["Check the login flow every 15 minutes and alert Teams"],
     requires: [{ kind: "live_model" }, { kind: "monitor_alerts", optional: true }],
     docs: [{ doc: "HOW_TO_USE.md", heading: "9. Monitoring" }],
+    playbook: [{ heading: "Monitoring", when: "checks on a schedule, with alerts" }],
   },
   {
     id: "notifications",
@@ -340,6 +377,7 @@ export const CAPABILITIES: Capability[] = [
       { kind: "either", of: [{ kind: "command", command: "gh", why: "for GitHub Actions" }, { kind: "command", command: "az", why: "for Azure Pipelines" }] },
     ],
     docs: [{ doc: "HOW_TO_USE.md", heading: "8. Pipelines" }],
+    playbook: [{ heading: "CI pipelines", when: "a GitHub Actions or Azure DevOps pipeline that runs ForgeQE or the tests" }],
   },
   {
     id: "systems",
@@ -356,13 +394,17 @@ export const CAPABILITIES: Capability[] = [
     ],
     requires: [{ kind: "system", anyOf: ["azure_devops", "jira", "xray", "confluence"] }],
     docs: [{ doc: "README.md", heading: "Azure DevOps, Jira, and other systems" }],
+    playbook: [
+      { heading: "Releases and pipelines in Azure DevOps", when: "releases, deployments, environments, or pipeline runs in Azure DevOps" },
+      { heading: "Dashboards and wiki pages in Azure DevOps", when: "an Azure DevOps dashboard or wiki page" },
+    ],
   },
   {
     id: "setup-help",
     area: "Setup",
     title: "Setup, skills, and documentation",
     summary: "Shows the model profiles and MCP servers, installs or repairs the browser engine, creates a forgeqe.yaml, manages skills, and answers questions about ForgeQE from its documentation and this list.",
-    tools: ["forgeqe_setup", "capabilities"],
+    tools: ["forgeqe_setup", "capabilities", "playbook"],
     examples: ["What can you do?", "Which model am I using?", "How do I set up email alerts?"],
     requires: [],
     docs: [

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.