@flowriki/agent 0.1.0-beta.41 → 0.1.0-beta.43

package/dist/cli.js

@@ -14,16 +14,16 @@ import {
   helperRunner,
   mirrorCheckTargets,
   openRunSession,
+  parseGherkin,
   prepareBrowsers,
   replayCase,
   replayFlow,
   resolveCheckouts,
   resolveService,
   runtimeValue,
-  similarity,
   start,
   status
-} from "./chunk-ALLCHKXG.js";
+} from "./chunk-ZMHE47A5.js";
 
 // src/cli.ts
 import { parseArgs } from "util";
@@ -219,6 +219,20 @@ var ServiceClient = class {
     return this.call(`/api/agent/library?${query}`);
   }
   /** Test cases written, edited or linked in one commit; duplicates skipped. */
+  readCases(projectId, refs) {
+    const ids = refs.filter((r) => /^tc_/.test(r.trim()));
+    const names = refs.filter((r) => !/^tc_/.test(r.trim()));
+    const q = new URLSearchParams({ projectId, ...ids.length ? { ids: ids.join(",") } : {}, ...names.length ? { names: names.join("|") } : {} });
+    return this.call(`/api/agent/cases/read?${q}`);
+  }
+  /** Test cases written down — business steps, no flows yet — on Claude's
+   *  working branch. */
+  writeCases(projectId, groups, changeId) {
+    return this.call(
+      `/api/agent/cases/batch?projectId=${encodeURIComponent(projectId)}`,
+      { method: "POST", body: JSON.stringify({ groups, ...changeId ? { changeId } : {} }) }
+    );
+  }
   saveLibrary(projectId, input) {
     return this.call(`/api/agent/library?projectId=${encodeURIComponent(projectId)}`, { method: "POST", body: JSON.stringify(input) });
   }
@@ -754,7 +768,7 @@ ${lines.join("\n")}`;
     const note = others.length ? `
 Claude has ${others.length} other open branch${others.length === 1 ? "" : "es"} on this project \u2014 gather_branches puts them into this one, for one review.` : "";
     const after = draft.after?.length ? ` It starts after ${draft.after.map((a) => `"${a.name}"`).join(", ")}.` : "";
-    return `${what} ${where_}.${after}${vault} Its ${checkCount} check${checkCount === 1 ? " is" : "s are"} saved switched off \u2014 an automation switches on the ones it is about. Nothing is published yet.
+    return `${what} ${where_}.${after}${vault} Its ${checkCount} check${checkCount === 1 ? " is" : "s are"} saved switched off \u2014 a test case switches on the ones it is about. Nothing is published yet.
 Review and publish it here: ${review}${note}`;
   }
   /** A test case built from flows, without saving: its rows and every check,
@@ -837,9 +851,14 @@ THE MODEL \u2014 get this right before recording anything:
   something different.
 - A flow records checks (add_check) that prove each thing happened, but they
   are SAVED SWITCHED OFF: which ones matter depends on the test.
-- An AUTOMATION is the test. It strings flows together as rows (in the same
+- A TEST CASE is the test. It strings flows together as rows (in the same
   browser, or a new one for a second person) and switches on the checks it is
   about. Build it with preview_case, then save_case \u2014 which runs it first.
+- A test case can be WRITTEN BEFORE IT IS AUTOMATED: business steps (Given /
+  When / Then) and no flows \u2014 imported from a spreadsheet, or written with
+  write_test_cases. To automate one, record the flows its steps need, then
+  save_case with the SAME name in the SAME folder: that fills it, and its
+  business steps stay. Its Then lines are the checks to switch on.
 - SIGN-IN is shared setup: a flow or case that needs somebody signed in uses a
   sign-in profile from the catalog (start_flow's signIn), never typed login steps.
   None yet? Make it: record the login as a flow that ends with a check proving
@@ -862,19 +881,9 @@ THE MODEL \u2014 get this right before recording anything:
   "Ordering \u2013 Pizza builder", "Checkout \u2013 Payment". Flows (features) and the
   cases built from them use the same names. Keep one area per folder.
 
-THE TEST LIBRARY is what the team checks, written down: test cases (TC-1,
-TC-2\u2026) with steps, expected results, priority and status. An automation is how
-a test case is checked by a machine, and each test case lists the automations
-that check it. Read it with library_cases before deciding what to automate \u2014
-the important cases nothing checks yet come first. Write cases with
-save_test_cases (a case the library already has is skipped, so writing the
-same thing twice is harmless), and after save_case, link the automation to the
-test cases it proves with link_test_case.
-
-KNOWLEDGE: project_brief is the project's memory \u2014 read it first. Search
-everything (knowledge pages, documents, requirements, test cases) with
-knowledge_search; read a page with knowledge_read; read documents with
-sources. product.md is "About the product": the person's own description of
+KNOWLEDGE: project_brief is the project's memory \u2014 read it first. Search the
+knowledge pages with knowledge_search; read one with knowledge_read.
+product.md is "About the product": the person's own description of
 the product, in their words, as long as they like \u2014 read it first. They
 write it, often with you in a conversation beside it; propose text there and
 let them decide, rather than writing product.md unless they ask you to.
@@ -885,32 +894,11 @@ as learned. Keep what you learn with write_knowledge (features/<name>.md,
 memory/decisions.md, a session summary), on Claude's branch for review \u2014
 never a password, key or token.
 
-FROM DOCUMENTS TO TESTS: documents (sources) are PRDs, CRs, feature docs.
-requirements lists what was found in them and what the latest version changed
-(new / changed / removed). For a new requirement: write test cases that cover
-it (save_test_cases with covers: [requirement id]) \u2014 but first check
-find_similar_cases, and link an existing case instead of writing a duplicate.
-For a changed one: update the cases that cover it. For a removed one: mark
-cases that only covered it deprecated. Never invent requirements.
-
-AUTOMATING A TEST CASE: first write the plan with save_automation_plan \u2014 flows
-to reuse, flows to record, which checks prove each expected result, accounts
-and helpers it needs, and anything that cannot be automated and why. Show it
-and wait for the person to approve before recording. Then record, save_case,
-and link_test_case.
-
-MANUAL TESTING: a test cycle is a set of library cases a person runs by hand
-("Release 4.2 regression"); each case is marked passed, failed, blocked or
-skipped, step by step, with a bug raised from the step that broke. Read them
-with test_cycles and bugs; make and change cycles with manage_cycle; record
-what happened with record_result; raise or update bugs with save_bug. Never
-mark a case passed on a person's behalf without being told it passed.
-
 HOW TO WORK:
 1. Call project_catalog. Reuse what exists \u2014 published, and on Claude's working
    branch \u2014 rather than writing it again.
 2. Before recording, say the plan to the person: the folders, the building-block
-   flows (and what each starts after), and the automations (rows + what each
+   flows (and what each starts after), and the test cases (rows + what each
    checks). Then record the blocks, earliest first.
 3. Record with start_flow (pass "after" for the flows it continues from), read
    the page with read_page, and act using the role and name EXACTLY as the page
@@ -921,7 +909,7 @@ HOW TO WORK:
    catalog, then type {{its saveAs name}} into the field that needs it.
 5. Add checks for what each step proves (a heading, a message, a value, the
    URL). replay_flow, then save_flow. A flow must record at least one check.
-6. Build each automation: preview_case lists its rows and every check, numbered;
+6. Build each test case: preview_case lists its rows and every check, numbered;
    save_case with the numbers to switch on runs the whole case and saves it only
    if it passed. Give the person the review link.
 7. Saving the same name again replaces it on the working branch. Old branches
@@ -936,7 +924,7 @@ A test that types a fixed new email passes once and fails every run after.`;
 var CASE_INPUT = {
   type: "object",
   properties: {
-    name: { type: "string", description: 'The automation: the scenario it proves, e.g. "Wrong password is refused".' },
+    name: { type: "string", description: 'The test case: the scenario it proves, e.g. "Wrong password is refused".' },
     folder: { type: "string", description: 'The case folder \u2014 area and topic, e.g. "Account \u2013 Sign in". Made if new.' },
     description: { type: "string" },
     rows: {
@@ -1303,8 +1291,8 @@ ${page}`);
     },
     {
       name: "preview_case",
-      title: "Preview an automation",
-      description: "Build an automation from flows without saving or running it: its rows (each flow with what it starts after folded in, and which browser it runs in) and every check, numbered, with which are on. Use the numbers in save_case.",
+      title: "Preview a test case",
+      description: "Build a test case from flows without saving or running it: its rows (each flow with what it starts after folded in, and which browser it runs in) and every check, numbered, with which are on. Use the numbers in save_case.",
       inputSchema: CASE_INPUT,
       annotations: { readOnlyHint: true },
       run: async (args) => {
@@ -1314,8 +1302,8 @@ ${page}`);
     },
     {
       name: "save_case",
-      title: "Run and save an automation",
-      description: "Build the automation, run it from the start in a fresh browser exactly as a test run will, and \u2014 only if every row passed \u2014 save it onto Claude's working branch. Saving the same name in the same folder again replaces it. Refused if it switches on no checks.",
+      title: "Run and save a test case",
+      description: "Build the test case, run it from the start in a fresh browser exactly as a test run will, and \u2014 only if every row passed \u2014 save it onto Claude's working branch. Saving the same name in the same folder again replaces it. Refused if it switches on no checks.",
       inputSchema: CASE_INPUT,
       annotations: { openWorldHint: true },
       run: async (args) => {
@@ -1325,10 +1313,90 @@ ${page}`);
         return text(out);
       }
     },
+    {
+      name: "read_test_cases",
+      title: "Read test cases",
+      description: "Read test cases by id (tc_\u2026) or exact name: their feature, business steps (Given / When / Then), whether they are automated, and the flows they run. Read a case's steps before automating it.",
+      inputSchema: {
+        type: "object",
+        properties: { projectId: { type: "string" }, cases: { type: "array", items: { type: "string" }, description: "Ids or names." } },
+        required: ["cases"],
+        additionalProperties: false
+      },
+      annotations: { readOnlyHint: true },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const refs = Array.isArray(args["cases"]) ? args["cases"].map(String) : [];
+        const { cases, missing } = await service.readCases(projectId, refs);
+        const parts = cases.map((c) => [
+          `${c.folder} \u203A ${c.name} (${c.id}) \u2014 ${c.automated ? `automated, rows: ${c.rows.join(" \u2192 ")}` : "not automated yet"}`,
+          ...c.description ? [`  ${c.description}`] : [],
+          ...c.businessSteps.length ? c.businessSteps.map((s) => `  ${s.keyword} ${s.text}`) : ["  (no business steps written)"]
+        ].join("\n"));
+        if (missing.length) parts.push(`Not found: ${missing.join(", ")} \u2014 project_catalog lists the test cases.`);
+        return text(parts.join("\n\n") || "No test cases found.");
+      }
+    },
+    {
+      name: "write_test_cases",
+      title: "Write test cases down, before automating them",
+      description: "Write test cases as business steps \u2014 Given / When / Then \u2014 with no flows yet, grouped by feature (the case folder), on Claude's working branch for review. They show as not automated until a test case with the same name is saved into the same folder with save_case, which keeps these steps. A case its folder already has is skipped. Use it when asked to write, plan or list test cases; record and save_case only when asked to automate.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          projectId: { type: "string" },
+          features: {
+            type: "array",
+            description: 'One entry per feature (case folder), e.g. "Account \u2013 Sign up".',
+            items: {
+              type: "object",
+              properties: {
+                feature: { type: "string" },
+                cases: {
+                  type: "array",
+                  items: {
+                    type: "object",
+                    properties: {
+                      name: { type: "string", description: 'The scenario it proves, e.g. "A taken email is refused".' },
+                      description: { type: "string" },
+                      steps: { type: "array", description: `Given / When / Then lines, e.g. "Given the sign-up form is open", "When I sign up with a taken email", "Then I see 'That email is taken'". And / But continue the line above.`, items: { type: "string" } }
+                    },
+                    required: ["name", "steps"],
+                    additionalProperties: false
+                  }
+                }
+              },
+              required: ["feature", "cases"],
+              additionalProperties: false
+            }
+          },
+          branch: { type: "string", description: "Optional: the id of one of Claude's open branches to write to (list_my_branches). Default: the working branch." }
+        },
+        required: ["features"],
+        additionalProperties: false
+      },
+      run: async (args) => {
+        const projectId = await projectFor(args["projectId"]);
+        const features = Array.isArray(args["features"]) ? args["features"] : [];
+        const groups = features.map((f) => ({
+          folder: String(f.feature ?? "").trim(),
+          cases: (Array.isArray(f.cases) ? f.cases : []).map((c) => {
+            const lines = Array.isArray(c.steps) ? c.steps.map(String) : [];
+            const steps = parseGherkin(lines.join("\n"));
+            if (!steps) throw new Error(`the steps of "${String(c.name ?? "")}" must each start with Given, When, Then, And or But`);
+            return { name: String(c.name ?? "").trim(), ...typeof c.description === "string" ? { description: c.description } : {}, businessSteps: steps };
+          })
+        }));
+        const done = await service.writeCases(projectId, groups, str(args["branch"]));
+        catalogs.delete(projectId);
+        const skipped = done.skipped.length ? ` Skipped ${done.skipped.length} the folder already had: ${done.skipped.map((s) => `"${s.name}"`).join(", ")}.` : "";
+        return text(`Wrote ${done.created.length} test case${done.created.length === 1 ? "" : "s"}, not automated yet, on Claude's working branch ${done.branch}.${skipped}`);
+      }
+    },
     {
       name: "create_sign_in",
       title: "Make a sign-in profile",
-      description: "Turn a saved login flow into a sign-in profile that flows and automations can start signed in with. The flow must not itself sign in or start after other flows, and must end with a check proving the login worked \u2014 its last check is switched on here. Returns the fields an account fills in. Making the same name again replaces Claude's earlier one.",
+      description: "Turn a saved login flow into a sign-in profile that flows and test cases can start signed in with. The flow must not itself sign in or start after other flows, and must end with a check proving the login worked \u2014 its last check is switched on here. Returns the fields an account fills in. Making the same name again replaces Claude's earlier one.",
       inputSchema: {
         type: "object",
         properties: {
@@ -1360,7 +1428,7 @@ Next: create_account for each person who signs in this way.`);
     {
       name: "create_account",
       title: "Make a sign-in account",
-      description: "An account for a sign-in profile: who signs in, and the values its login flow types, by field label (create_sign_in and project_catalog list them). Secret fields are sealed in the project's vault and never shown again. Then start_flow / automations can use signIn {profileId, accountId}. Making the same name again updates Claude's earlier one.",
+      description: "An account for a sign-in profile: who signs in, and the values its login flow types, by field label (create_sign_in and project_catalog list them). Secret fields are sealed in the project's vault and never shown again. Then start_flow / test cases can use signIn {profileId, accountId}. Making the same name again updates Claude's earlier one.",
       inputSchema: {
         type: "object",
         properties: {
@@ -1419,134 +1487,15 @@ Use it with start_flow signIn {"profileId": "\u2026", "accountId": "${made.accou
         return text(`${made.replaced ? "Updated" : "Made"} the ${made.kind} helper "${made.name}" (id ${made.helperId}) on Claude's working branch ${made.branch}.${made.inputs.length ? ` A step supplies ${made.inputs.map((n) => `{{${n}}}`).join(", ")}.` : ""} Use it with use_helper.`);
       }
     },
-    {
-      name: "library_cases",
-      title: "Read the test library",
-      description: "The project's test cases \u2014 what the team checks \u2014 with their key (TC-n), priority, status, steps and expected results, and which automations check each one. Optional q (title, key or tag) and featureId narrow it. Read before planning automations: cases with priority P0/P1 and no automation are the gaps.",
-      inputSchema: {
-        type: "object",
-        properties: {
-          projectId: { type: "string" },
-          q: { type: "string", description: "Words in the title, a key like TC-12, or a tag." },
-          featureId: { type: "string", description: "Only this feature's cases, e.g. f_checkout." }
-        },
-        additionalProperties: false
-      },
-      annotations: { readOnlyHint: true },
-      run: async (args) => {
-        const projectId = await projectFor(args["projectId"]);
-        const { cases, total } = await service.library(projectId, {
-          ...str(args["q"]) ? { q: str(args["q"]) } : {},
-          ...str(args["featureId"]) ? { featureId: str(args["featureId"]) } : {}
-        });
-        if (cases.length === 0) return text(total ? "No test case matches." : "The test library is empty. Write cases with save_test_cases.");
-        const lines = cases.map((c) => {
-          const automated = c.automation.links.length ? `automated by ${c.automation.links.map((l) => l.automationId).join(", ")}${c.automation.links.some((l) => l.caseRevision < c.revision) ? " (case changed since \u2014 check it still matches)" : ""}` : c.automation.state === "not-automatable" ? `manual only: ${c.automation.reason ?? ""}` : c.automation.state === "planned" ? "automation planned" : "NOT AUTOMATED";
-          const steps = c.steps.map((st, i) => `   ${i + 1}. ${st.action}${st.data ? ` [${st.data}]` : ""}${st.expected ? ` \u2192 ${st.expected}` : ""}`).join("\n");
-          return `${c.key} (id ${c.id}, revision ${c.revision}) ${c.title} \u2014 ${c.featureId}, ${c.priority}, ${c.status}, ${automated}${c.preconditions.length ? `
-   Preconditions: ${c.preconditions.join("; ")}` : ""}${steps ? `
-${steps}` : ""}`;
-        });
-        return text(`${cases.length} of ${total} test cases:
-${lines.join("\n")}`);
-      }
-    },
-    {
-      name: "save_test_cases",
-      title: "Write test cases",
-      description: `Add test cases to the library, or edit existing ones, in one commit on Claude's working branch. create: [{feature: "Checkout" (or featureId), title, priority?: P0|P1|P2|P3, type?: functional|negative|edge|regression|smoke|accessibility|other, status?: draft|ready|deprecated, preconditions?: [..], steps: [{action, data?, expected?}], tags?: [..], description?}]. update: [{id, revision (from library_cases), ...only the fields to change}]. A new case the library already has is skipped and named in the answer \u2014 never duplicated.`,
-      inputSchema: {
-        type: "object",
-        properties: {
-          projectId: { type: "string" },
-          create: { type: "array", items: { type: "object" } },
-          update: { type: "array", items: { type: "object" } },
-          branch: { type: "string", description: "Optional: the id of one of Claude's open branches to write to (list_my_branches). Default: the working branch." }
-        },
-        additionalProperties: false
-      },
-      run: async (args) => {
-        const projectId = await projectFor(args["projectId"]);
-        const featureOf = (item) => {
-          const id = str(item["featureId"]);
-          if (id) return id;
-          const name = str(item["feature"]) ?? "General";
-          return `f_${name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "general"}`;
-        };
-        const create = (Array.isArray(args["create"]) ? args["create"] : []).map((raw) => {
-          const { feature: _feature, ...item } = raw;
-          return { ...item, featureId: featureOf(raw) };
-        });
-        const update = (Array.isArray(args["update"]) ? args["update"] : []).map((raw) => {
-          const item = raw;
-          if (item["feature"] === void 0) return item;
-          const { feature: _feature, ...rest } = item;
-          return { ...rest, featureId: featureOf(item) };
-        });
-        const saved = await service.saveLibrary(projectId, {
-          create,
-          update,
-          message: "Test cases written with Claude",
-          ...str(args["branch"]) ? { changeId: str(args["branch"]) } : {}
-        });
-        const made = saved.created.map((c) => `${c.key} ${c.title} (id ${c.id})`);
-        const edited = saved.updated.map((c) => `${c.key} ${c.title}`);
-        return text([
-          made.length ? `Added ${made.length}: ${made.join("; ")}.` : "",
-          edited.length ? `Updated ${edited.length}: ${edited.join("; ")}.` : "",
-          saved.duplicates.length ? `Skipped ${saved.duplicates.length} already in the library: ${saved.duplicates.map((d) => `"${d.title}" is ${d.matches}`).join("; ")}.` : "",
-          `On Claude's working branch ${saved.branch}.`
-        ].filter(Boolean).join(" "));
-      }
-    },
-    {
-      name: "link_test_case",
-      title: "Link an automation to a test case",
-      description: "Record that an automation (a case id from save_case or project_catalog) checks a library test case (its key like TC-12, or its id). unlink: true removes the link. Do this after save_case for every test case the automation proves.",
-      inputSchema: {
-        type: "object",
-        properties: {
-          projectId: { type: "string" },
-          testCase: { type: "string", description: "TC-12, or the test case id." },
-          automationId: { type: "string" },
-          unlink: { type: "boolean" },
-          branch: { type: "string" }
-        },
-        required: ["testCase", "automationId"],
-        additionalProperties: false
-      },
-      run: async (args) => {
-        const projectId = await projectFor(args["projectId"]);
-        const wanted = str(args["testCase"]) ?? "";
-        const automationId = str(args["automationId"]) ?? "";
-        const { cases } = await service.library(projectId);
-        const target = cases.find((c) => c.id === wanted || c.key.toLowerCase() === wanted.toLowerCase());
-        if (!target) return text(`No test case ${wanted} in the library \u2014 library_cases lists them.`);
-        const has = target.automation.links.some((l) => l.automationId === automationId);
-        const unlink = args["unlink"] === true;
-        if (has !== unlink) return text(`${target.key} is ${unlink ? "not" : "already"} linked to ${automationId}.`);
-        const links = unlink ? target.automation.links.filter((l) => l.automationId !== automationId) : [...target.automation.links, { automationId, caseRevision: target.revision + 1, at: (/* @__PURE__ */ new Date()).toISOString(), by: "Claude" }];
-        const state = links.length ? "automated" : target.automation.state === "automated" ? "none" : target.automation.state;
-        const saved = await service.saveLibrary(projectId, {
-          update: [{ id: target.id, revision: target.revision, automation: { ...target.automation, state, links } }],
-          message: `${unlink ? "Unlink" : "Link"} ${target.key} ${unlink ? "from" : "to"} ${automationId}`,
-          ...str(args["branch"]) ? { changeId: str(args["branch"]) } : {}
-        });
-        return text(`${unlink ? "Unlinked" : "Linked"} ${target.key} "${target.title}" ${unlink ? "from" : "to"} automation ${automationId}, on Claude's working branch ${saved.branch}.`);
-      }
-    },
     {
       name: "project_brief",
       title: "Read the project's memory",
-      description: "The project's own knowledge, in one call: About the product (product.md), memory/decisions.md, what each linked codebase folder was learned as, the list of feature pages and session summaries, and the documents it has. Call it first in every conversation.",
+      description: "The project's own knowledge, in one call: About the product (product.md), memory/decisions.md, what each linked codebase folder was learned as, and the list of feature pages and session summaries. Call it first in every conversation.",
       inputSchema: { type: "object", properties: { projectId: { type: "string" } }, additionalProperties: false },
       annotations: { readOnlyHint: true },
       run: async (args) => {
         const projectId = await projectFor(args["projectId"]);
-        const [{ pages }, { sources }] = await Promise.all([
-          service.knowledgePages(projectId),
-          service.sources(projectId).catch(() => ({ sources: [] }))
-        ]);
+        const { pages } = await service.knowledgePages(projectId);
         const read = async (path) => pages.some((p) => p.path === path) ? (await service.knowledgePage(projectId, path)).content : null;
         const [product, glossary, decisions] = await Promise.all(["product.md", "glossary.md", "memory/decisions.md"].map(read));
         const codebases = pages.filter((p) => p.path.startsWith("codebase/"));
@@ -1562,9 +1511,7 @@ ${decisions}` : "",
           codebases.length ? `## Codebase, as learned
 ${headers.join("\n")}` : "No codebase learned yet.",
           `## Other pages
-${pages.filter((p) => !shown.has(p.path)).map((p) => `- ${p.path}`).join("\n") || "none"}`,
-          `## Documents
-${sources.map((s) => `- ${s.title} (id ${s.id}, v${s.version}) \u2014 requirements: ${s.requirements["new"] ?? 0} new, ${s.requirements["changed"] ?? 0} changed, ${s.requirements["active"] ?? 0} unchanged, ${s.requirements["removed"] ?? 0} removed`).join("\n") || "none"}`
+${pages.filter((p) => !shown.has(p.path)).map((p) => `- ${p.path}`).join("\n") || "none"}`
         ];
         return text(parts.filter(Boolean).join("\n\n"));
       }
@@ -1616,353 +1563,6 @@ ${sources.map((s) => `- ${s.title} (id ${s.id}, v${s.version}) \u2014 requiremen
         return text(`Wrote ${saved.path} (${saved.length} characters) on Claude's working branch ${saved.branch}.`);
       }
     },
-    {
-      name: "sources",
-      title: "Read source documents",
-      description: "Without sourceId: every source (PRDs, CRs, feature docs, Jira stories, Figma files\u2026) with its version and how many requirements are new, changed, unchanged or removed. With sourceId: the latest version's text.",
-      inputSchema: { type: "object", properties: { projectId: { type: "string" }, sourceId: { type: "string" } }, additionalProperties: false },
-      annotations: { readOnlyHint: true },
-      run: async (args) => {
-        const projectId = await projectFor(args["projectId"]);
-        const id = str(args["sourceId"]);
-        if (id) {
-          const source = await service.source(projectId, id);
-          return text(`# ${source.title} (v${source.version})
-
-${source.text.slice(0, 6e4)}`);
-        }
-        const { sources } = await service.sources(projectId);
-        if (!sources.length) return text("No sources yet. add_source adds a document by text or link; the Knowledge screen takes files.");
-        return text(sources.map((s) => `${s.title} (id ${s.id}, v${s.version}, ${s.kind}${s.externalUrl ? `, ${s.externalUrl}` : ""}) \u2014 ${s.requirements["new"] ?? 0} new, ${s.requirements["changed"] ?? 0} changed, ${s.requirements["active"] ?? 0} unchanged, ${s.requirements["removed"] ?? 0} removed`).join("\n"));
-      }
-    },
-    {
-      name: "add_source",
-      title: "Add a source document",
-      description: "Add a document tests are written from \u2014 as text (Markdown is best: headings and lists are how requirements are found) or as a public link \u2014 or a new version of one (sourceId). The same text again is not a new version. Requirements are found and compared at once.",
-      inputSchema: {
-        type: "object",
-        properties: { projectId: { type: "string" }, title: { type: "string" }, text: { type: "string" }, url: { type: "string" }, sourceId: { type: "string" } },
-        additionalProperties: false
-      },
-      run: async (args) => {
-        const projectId = await projectFor(args["projectId"]);
-        const made = await service.addSource(projectId, {
-          ...str(args["title"]) ? { title: str(args["title"]) } : {},
-          ...typeof args["text"] === "string" ? { text: args["text"] } : {},
-          ...str(args["url"]) ? { url: str(args["url"]) } : {}
-        }, str(args["sourceId"]));
-        const r = made.requirements;
-        return text(made.changed ? `${made.source.title} is now v${made.source.version} (id ${made.source.id}). Requirements: ${r["added"] ?? 0} new, ${r["changed"] ?? 0} changed, ${r["unchanged"] ?? 0} unchanged, ${r["removed"] ?? 0} removed.` : `${made.source.title} has not changed since v${made.source.version}; nothing new.`);
-      }
-    },
-    {
-      name: "delete_source",
-      title: "Delete a source document",
-      description: "Delete a source and everything found in it, for good. Only after the person has said to.",
-      inputSchema: { type: "object", properties: { projectId: { type: "string" }, sourceId: { type: "string" } }, required: ["sourceId"], additionalProperties: false },
-      annotations: { destructiveHint: true },
-      run: async (args) => {
-        const projectId = await projectFor(args["projectId"]);
-        await service.deleteSource(projectId, str(args["sourceId"]) ?? "");
-        return text(`Deleted the source ${str(args["sourceId"])} and its requirements.`);
-      }
-    },
-    {
-      name: "update_requirement",
-      title: "File or correct a requirement",
-      description: "Set which feature a requirement belongs to (featureId like f_checkout), or correct its wording where extraction got it wrong.",
-      inputSchema: { type: "object", properties: { projectId: { type: "string" }, requirementId: { type: "string" }, featureId: { type: "string" }, text: { type: "string" } }, required: ["requirementId"], additionalProperties: false },
-      run: async (args) => {
-        const projectId = await projectFor(args["projectId"]);
-        const saved = await service.updateRequirement(projectId, str(args["requirementId"]) ?? "", {
-          ...typeof args["featureId"] === "string" ? { featureId: args["featureId"] } : {},
-          ...str(args["text"]) ? { text: str(args["text"]) } : {}
-        });
-        return text(`${saved.id}${saved.featureId ? ` is filed under ${saved.featureId}` : ""}: ${saved.text}`);
-      }
-    },
-    {
-      name: "requirements",
-      title: "Read requirements",
-      description: "Requirements found in sources, each with where it is (heading path), its state as of the source's latest version \u2014 new, changed (with what it said before), active (unchanged) or removed \u2014 and its id for covers. Optional sourceId and state narrow it.",
-      inputSchema: { type: "object", properties: { projectId: { type: "string" }, sourceId: { type: "string" }, state: { type: "string", enum: ["new", "changed", "active", "removed"] } }, additionalProperties: false },
-      annotations: { readOnlyHint: true },
-      run: async (args) => {
-        const projectId = await projectFor(args["projectId"]);
-        const [{ requirements }, { cases }] = await Promise.all([
-          service.requirements(projectId, { ...str(args["sourceId"]) ? { sourceId: str(args["sourceId"]) } : {}, ...str(args["state"]) ? { state: str(args["state"]) } : {} }),
-          service.library(projectId)
-        ]);
-        if (!requirements.length) return text("No requirements match.");
-        return text(requirements.map((r) => {
-          const covering = cases.filter((c) => c.covers.includes(r.id)).map((c) => c.key);
-          return `${r.id} [${r.state}] ${r.sourceTitle} \u203A ${r.anchor}: ${r.text}${r.state === "changed" && r.history.length ? `
-   was: ${r.history.at(-1).text}` : ""}
-   covered by: ${covering.join(", ") || "nothing yet"}`;
-        }).join("\n"));
-      }
-    },
-    {
-      name: "find_similar_cases",
-      title: "Find test cases like this one",
-      description: "Before writing a test case, find existing ones that may already check the same thing \u2014 by title and steps. You judge whether one is really the same; if it is, link the requirement to it (covers) instead of writing a duplicate.",
-      inputSchema: { type: "object", properties: { projectId: { type: "string" }, text: { type: "string", description: "The case you are about to write: its title and steps." } }, required: ["text"], additionalProperties: false },
-      annotations: { readOnlyHint: true },
-      run: async (args) => {
-        const projectId = await projectFor(args["projectId"]);
-        const wanted = String(args["text"] ?? "");
-        const { cases } = await service.library(projectId);
-        const scored = cases.map((c) => ({ c, score: similarity(wanted, [c.title, ...c.steps.flatMap((st) => [st.action, st.expected ?? ""])].join(" ")) })).filter((x) => x.score >= 0.2).sort((a, b) => b.score - a.score).slice(0, 8);
-        if (!scored.length) return text("Nothing similar in the library.");
-        return text(scored.map(({ c, score }) => `${c.key} (id ${c.id}, revision ${c.revision}, ${Math.round(score * 100)}% alike) ${c.title}
-${c.steps.map((st, i) => `   ${i + 1}. ${st.action}${st.expected ? ` \u2192 ${st.expected}` : ""}`).join("\n")}`).join("\n"));
-      }
-    },
-    {
-      name: "save_automation_plan",
-      title: "Write the plan to automate a test case",
-      description: "Save the plan for automating a test case (TC key or id) before recording anything: flows to reuse, flows to record, which check proves each expected result, accounts and helpers it needs, and what cannot be automated and why. Marks it planned. approved: true only when the person has said the plan is right.",
-      inputSchema: {
-        type: "object",
-        properties: { projectId: { type: "string" }, testCase: { type: "string" }, plan: { type: "string" }, approved: { type: "boolean" }, branch: { type: "string" } },
-        required: ["testCase", "plan"],
-        additionalProperties: false
-      },
-      run: async (args) => {
-        const projectId = await projectFor(args["projectId"]);
-        const ref = str(args["testCase"]) ?? "";
-        const { cases } = await service.library(projectId);
-        const target = cases.find((c) => c.id === ref || c.key.toLowerCase() === ref.toLowerCase());
-        if (!target) return text(`No test case ${ref} in the library.`);
-        const saved = await service.saveLibrary(projectId, {
-          update: [{
-            id: target.id,
-            revision: target.revision,
-            automation: {
-              ...target.automation,
-              plan: String(args["plan"] ?? ""),
-              planApproved: args["approved"] === true,
-              state: target.automation.links.length ? target.automation.state : "planned"
-            }
-          }],
-          message: `Automation plan for ${target.key}`,
-          ...str(args["branch"]) ? { changeId: str(args["branch"]) } : {}
-        });
-        return text(`Saved the ${args["approved"] === true ? "approved " : ""}automation plan for ${target.key} "${target.title}" on Claude's working branch ${saved.branch}.`);
-      }
-    },
-    {
-      name: "test_cycles",
-      title: "Read manual test cycles",
-      description: "Manual test cycles and how they are going. Without cycleId: every cycle with its counts (passed, failed, blocked, untested). With cycleId: each case in it \u2014 key, title, steps, the outcome of each step, notes, evidence and bugs.",
-      inputSchema: {
-        type: "object",
-        properties: { projectId: { type: "string" }, cycleId: { type: "string" } },
-        additionalProperties: false
-      },
-      annotations: { readOnlyHint: true },
-      run: async (args) => {
-        const projectId = await projectFor(args["projectId"]);
-        const counts = (s) => `${s.passed} passed, ${s.failed} failed, ${s.blocked} blocked, ${s.skipped} skipped, ${s.untested} untested of ${s.total}`;
-        const id = str(args["cycleId"]);
-        if (!id) {
-          const { cycles } = await service.cycles(projectId);
-          if (!cycles.length) return text("No test cycles yet. manage_cycle with action create makes one from library cases.");
-          return text(cycles.map((c) => `${c.name} (id ${c.id}, ${c.status}) \u2014 ${counts(c.summary)}`).join("\n"));
-        }
-        const cycle = await service.cycle(projectId, id);
-        const lines = cycle.entries.map((e) => {
-          const r = e.result;
-          const steps = e.steps.map((st, i) => {
-            const got = r?.steps.find((x) => x.stepId === st.id);
-            return `   ${i + 1}. ${st.action}${st.expected ? ` \u2192 ${st.expected}` : ""}: ${got?.outcome ?? "untested"}${got?.actual ? ` (actual: ${got.actual})` : ""}`;
-          }).join("\n");
-          return `${e.key} ${e.title} [${e.priority}] \u2014 ${r?.outcome ?? "untested"}${e.assignee ? `, assigned to ${e.assignee}` : ""}${r?.note ? `
-   Note: ${r.note}` : ""}${r?.bugIds.length ? `
-   Bugs: ${r.bugIds.join(", ")}` : ""}${r?.evidence.length ? `
-   Evidence: ${r.evidence.map((ev) => ev.url ? `${ev.name} <${ev.url}>` : ev.name).join(", ")}` : ""}${steps ? `
-${steps}` : ""}`;
-        });
-        return text(`${cycle.name} (${cycle.status}) \u2014 ${counts(cycle.summary)}
-${lines.join("\n")}`);
-      }
-    },
-    {
-      name: "manage_cycle",
-      title: "Make or change a test cycle",
-      description: "action create: {name, description?, testCases: [TC keys or ids]} \u2014 cases are taken from the library as they are now (on Claude's working branch when it has one). action update: {cycleId, name?, description?, addTestCases?, removeTestCases?, assign?: {testCase, assignee}}. action close / reopen: {cycleId}. action delete: {cycleId} \u2014 deletes the cycle and its results for good; only after the person has said to.",
-      inputSchema: {
-        type: "object",
-        properties: {
-          projectId: { type: "string" },
-          action: { type: "string", enum: ["create", "update", "close", "reopen", "delete"] },
-          cycleId: { type: "string" },
-          name: { type: "string" },
-          description: { type: "string" },
-          testCases: { type: "array", items: { type: "string" } },
-          addTestCases: { type: "array", items: { type: "string" } },
-          removeTestCases: { type: "array", items: { type: "string" } },
-          assign: { type: "object", properties: { testCase: { type: "string" }, assignee: { type: "string" } }, additionalProperties: false }
-        },
-        required: ["action"],
-        additionalProperties: false
-      },
-      run: async (args) => {
-        const projectId = await projectFor(args["projectId"]);
-        const action = str(args["action"]);
-        const cycleId = str(args["cycleId"]);
-        const resolve = async (refs) => {
-          const wanted = Array.isArray(refs) ? refs.map(String) : [];
-          if (!wanted.length) return { ids: [], changeId: void 0 };
-          const lib = await service.library(projectId);
-          const ids = wanted.map((ref) => lib.cases.find((c) => c.id === ref || c.key.toLowerCase() === ref.toLowerCase())?.id);
-          const missing = wanted.filter((_, i) => !ids[i]);
-          if (missing.length) throw new Error(`no test case ${missing.join(", ")} in the library \u2014 library_cases lists them`);
-          return { ids, changeId: lib.changeId };
-        };
-        if (action === "create") {
-          const name = str(args["name"]);
-          if (!name) return text("A cycle needs a name.");
-          const { ids, changeId } = await resolve(args["testCases"]);
-          const made = await service.createCycle(projectId, { name, ...str(args["description"]) ? { description: str(args["description"]) } : {}, testCaseIds: ids }, changeId);
-          return text(`Made the cycle "${made.name}" (id ${made.id}) with ${made.entries.length} case${made.entries.length === 1 ? "" : "s"}: ${made.entries.map((e) => e.key).join(", ")}.`);
-        }
-        if (!cycleId) return text("Say which cycle (cycleId \u2014 test_cycles lists them).");
-        if (action === "delete") {
-          await service.deleteCycle(projectId, cycleId);
-          return text(`Deleted the cycle ${cycleId} and its results.`);
-        }
-        if (action === "close" || action === "reopen") {
-          const saved2 = await service.updateCycle(projectId, cycleId, { status: action === "close" ? "closed" : "open" });
-          return text(`${saved2.name} is ${saved2.status}.`);
-        }
-        const current = await service.cycle(projectId, cycleId);
-        const inCycle = (ref) => current.entries.find((e) => e.testCaseId === ref || e.key.toLowerCase() === ref.toLowerCase())?.testCaseId;
-        const added = await resolve(args["addTestCases"]);
-        const body = {
-          ...str(args["name"]) ? { name: str(args["name"]) } : {},
-          ...typeof args["description"] === "string" ? { description: args["description"] } : {},
-          ...added.ids.length ? { addCaseIds: added.ids } : {},
-          ...Array.isArray(args["removeTestCases"]) ? { removeCaseIds: args["removeTestCases"].map(String).map((r) => inCycle(r) ?? r) } : {}
-        };
-        const assign = args["assign"];
-        if (assign?.testCase) body["assign"] = { testCaseId: inCycle(assign.testCase) ?? assign.testCase, assignee: assign.assignee ?? "" };
-        const saved = await service.updateCycle(projectId, cycleId, body, added.changeId);
-        return text(`Updated "${saved.name}": ${saved.entries.length} case${saved.entries.length === 1 ? "" : "s"} (${saved.entries.map((e) => e.key).join(", ")}).`);
-      }
-    },
-    {
-      name: "record_result",
-      title: "Record how a case went",
-      description: "Record a manual result for one case in a cycle: steps [{step: its number (1, 2\u2026), outcome: passed|failed|blocked|skipped|untested, actual?: what really happened}], or a whole outcome, a note, links as evidence ([{name, url}]). Any failed step fails the case. retest: true keeps the earlier attempt in the case's history. Only record what the person tells you happened.",
-      inputSchema: {
-        type: "object",
-        properties: {
-          projectId: { type: "string" },
-          cycleId: { type: "string" },
-          testCase: { type: "string", description: "TC-12, or the test case id." },
-          steps: { type: "array", items: { type: "object" } },
-          outcome: { type: "string", enum: ["passed", "failed", "blocked", "skipped", "untested"] },
-          note: { type: "string" },
-          retest: { type: "boolean" },
-          evidenceLinks: { type: "array", items: { type: "object", properties: { name: { type: "string" }, url: { type: "string" } }, additionalProperties: false } }
-        },
-        required: ["cycleId", "testCase"],
-        additionalProperties: false
-      },
-      run: async (args) => {
-        const projectId = await projectFor(args["projectId"]);
-        const cycleId = str(args["cycleId"]) ?? "";
-        const cycle = await service.cycle(projectId, cycleId);
-        const ref = str(args["testCase"]) ?? "";
-        const entry = cycle.entries.find((e) => e.testCaseId === ref || e.key.toLowerCase() === ref.toLowerCase());
-        if (!entry) return text(`${ref} is not in "${cycle.name}" \u2014 test_cycles lists its cases.`);
-        const steps = (Array.isArray(args["steps"]) ? args["steps"] : []).map((raw) => {
-          const item = raw;
-          const at = typeof item.step === "number" ? entry.steps[item.step - 1]?.id : void 0;
-          return { stepId: String(item.stepId ?? at ?? ""), outcome: String(item.outcome ?? ""), ...typeof item.actual === "string" ? { actual: item.actual } : {} };
-        });
-        const saved = await service.recordResult(projectId, cycleId, entry.testCaseId, {
-          steps,
-          ...str(args["outcome"]) ? { outcome: str(args["outcome"]) } : {},
-          ...typeof args["note"] === "string" ? { note: args["note"] } : {},
-          ...args["retest"] === true ? { retest: true } : {}
-        });
-        for (const link of Array.isArray(args["evidenceLinks"]) ? args["evidenceLinks"] : []) {
-          const { name, url } = link;
-          if (url) await service.addEvidenceLink(projectId, cycleId, entry.testCaseId, { name: name || "Evidence", url });
-        }
-        const now = saved.entries.find((e) => e.testCaseId === entry.testCaseId);
-        return text(`${entry.key} is ${now.result?.outcome ?? "untested"} in "${saved.name}". The cycle: ${saved.summary.passed} passed, ${saved.summary.failed} failed, ${saved.summary.blocked} blocked, ${saved.summary.untested} untested.`);
-      }
-    },
-    {
-      name: "bugs",
-      title: "Read bugs",
-      description: "The project's bugs: key (BUG-n), title, severity, status, and the test cases and cycle step they were found at. Optional status narrows it (open, in-progress, fixed, verified, closed, wont-fix).",
-      inputSchema: { type: "object", properties: { projectId: { type: "string" }, status: { type: "string" } }, additionalProperties: false },
-      annotations: { readOnlyHint: true },
-      run: async (args) => {
-        const projectId = await projectFor(args["projectId"]);
-        const { bugs } = await service.bugs(projectId);
-        const shown = str(args["status"]) ? bugs.filter((b) => b.status === str(args["status"])) : bugs;
-        if (!shown.length) return text("No bugs.");
-        return text(shown.map((b) => `${b.key} (id ${b.id}) ${b.title} \u2014 ${b.severity}, ${b.status}${b.testCaseIds.length ? `, test cases ${b.testCaseIds.join(", ")}` : ""}${b.description ? `
-   ${b.description.slice(0, 300)}` : ""}`).join("\n"));
-      }
-    },
-    {
-      name: "save_bug",
-      title: "Raise or update a bug",
-      description: "New: {title, description?, severity?: critical|major|minor|trivial, cycleId?, testCase?, step? (its number)} \u2014 found in a cycle, it is attached to that case's result there. Update: {bugId, title?, description?, severity?, status?: open|in-progress|fixed|verified|closed|wont-fix}.",
-      inputSchema: {
-        type: "object",
-        properties: {
-          projectId: { type: "string" },
-          bugId: { type: "string" },
-          title: { type: "string" },
-          description: { type: "string" },
-          severity: { type: "string" },
-          status: { type: "string" },
-          cycleId: { type: "string" },
-          testCase: { type: "string" },
-          step: { type: "number" }
-        },
-        additionalProperties: false
-      },
-      run: async (args) => {
-        const projectId = await projectFor(args["projectId"]);
-        const bugId = str(args["bugId"]);
-        if (bugId) {
-          const body2 = Object.fromEntries(["title", "description", "severity", "status"].filter((k) => typeof args[k] === "string").map((k) => [k, args[k]]));
-          const saved = await service.updateBug(projectId, bugId, body2);
-          return text(`${saved.key} "${saved.title}" is ${saved.status} (${saved.severity}).`);
-        }
-        const title = str(args["title"]);
-        if (!title) return text("A bug needs a title.");
-        const body = {
-          title,
-          ...typeof args["description"] === "string" ? { description: args["description"] } : {},
-          ...str(args["severity"]) ? { severity: str(args["severity"]) } : {}
-        };
-        const cycleId = str(args["cycleId"]);
-        const ref = str(args["testCase"]);
-        if (cycleId && ref) {
-          const cycle = await service.cycle(projectId, cycleId);
-          const entry = cycle.entries.find((e) => e.testCaseId === ref || e.key.toLowerCase() === ref.toLowerCase());
-          if (!entry) return text(`${ref} is not in that cycle.`);
-          const step = typeof args["step"] === "number" ? entry.steps[args["step"] - 1]?.id : void 0;
-          body["foundAt"] = { cycleId, testCaseId: entry.testCaseId, ...step ? { stepId: step } : {} };
-        } else if (ref) {
-          const lib = await service.library(projectId);
-          const found = lib.cases.find((c) => c.id === ref || c.key.toLowerCase() === ref.toLowerCase());
-          if (found) body["testCaseIds"] = [found.id];
-        }
-        const made = await service.createBug(projectId, body);
-        return text(`Raised ${made.key} "${made.title}" (${made.severity}).`);
-      }
-    },
     {
       name: "close_browser",
       title: "Close the browser",