qatools-cli 1.2.9 → 1.2.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/package.json +1 -1
  2. package/qatools.js +107 -8
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "qatools-cli",
3
- "version": "1.2.9",
3
+ "version": "1.2.11",
4
4
  "description": "CLI for QA Tools — requirements, epics, sprints, sessions, App Context sync, project agenda. The companion to qa-tools.com.",
5
5
  "scripts": {
6
6
  "release": "npm version patch --no-git-tag-version && npm publish",
package/qatools.js CHANGED
@@ -2619,6 +2619,10 @@ You generate test protocols (templates) from approved requirements.
2619
2619
  ## Rules
2620
2620
  - Every test MUST have requirementKey, requirementVersion, and purpose
2621
2621
  - Generate from BOTH acceptance criteria AND negative scenarios
2622
+
2623
+ ## Manual versus automated
2624
+ A test protocol is run by people. Put in it only what a person must check because you can't verify it yourself: look and feel, real mobile devices, e-mail/SMS actually arriving, BankID/Freja, printing/PDF, flows between several parties. Say in purpose why a person must do it. What you can verify yourself belongs in automated tests in the code (results reach qa-tools via \`qatools test-report\`).
2625
+ When planning a sprint, draft one such protocol per sprint (MCP: testProtocols in propose_sprint_plan, or create_test_protocol after a plan approved in the conversation). You never approve a protocol — a project member does.
2622
2626
  `,
2623
2627
 
2624
2628
  "qa-test-analyst.md": `---
@@ -2697,6 +2701,7 @@ If the qa-tools MCP server (\`qatools mcp\`) is available, use its tools and the
2697
2701
  2. Draft a proposal:
2698
2702
  - Only approved, functional requirements without a sprint are candidates. Continuous (non-functional) requirements are never planned — they are checked against every sprint.
2699
2703
  - Never touch completed sprints or requirements in one — the backend refuses.
2704
+ - Carry-over: approved or in-progress requirements in an overdue sprint (end date passed, not completed) may be proposed for a move to an open sprint — they keep status and assignee. Never move requirements out of a sprint that has not passed its end date.
2700
2705
  - An epic's requirements never go before the requirements of the epics it dependsOn.
2701
2706
  - Priority 1 first, then epic priority.
2702
2707
  - Per sprint: roughly the capacity average, counting requirements already in the sprint.
@@ -3688,7 +3693,7 @@ const mcpTools = [
3688
3693
  },
3689
3694
  {
3690
3695
  name: "sprint_velocity",
3691
- description: "Planning capacity: per completed sprint, how many of its requirements are implemented/tested, plus what is already planned in each open sprint. Statuses are today's, not a snapshot from when each sprint ended.",
3696
+ description: "Planning capacity: per completed sprint, how many requirements were planned and done, plus what is already planned in each open sprint. Completed sprints use the numbers stored when they were completed (fromSnapshot true); older ones are counted from today's statuses (fromSnapshot false). averageCompletionRate = average share of planned requirements that got done.",
3692
3697
  inputSchema: mcpSchema(),
3693
3698
  run: async (a) => {
3694
3699
  const [{ sprints }, { requirements }] = await Promise.all([
@@ -3698,15 +3703,22 @@ const mcpTools = [
3698
3703
  const DONE = new Set(["implemented", "tested"]);
3699
3704
  const active = requirements.filter(r => r.status !== "superseded" && r.status !== "rejected");
3700
3705
  const row = (s) => {
3706
+ const base = { id: s.id, name: s.name, status: s.status, startDate: s.startDate || "", releaseDate: s.releaseDate || "" };
3707
+ // sprint.completion-snapshot: completing moves the unfinished out, so only the stored numbers show what was planned.
3708
+ if (s.status === "completed" && s.completionStats) {
3709
+ return { ...base, planned: s.completionStats.planned, done: s.completionStats.done, moved: s.completionStats.moved, fromSnapshot: true };
3710
+ }
3701
3711
  const reqs = active.filter(r => r.sprintId === s.id);
3702
- return { id: s.id, name: s.name, status: s.status, startDate: s.startDate || "", releaseDate: s.releaseDate || "", planned: reqs.length, done: reqs.filter(r => DONE.has(r.status)).length };
3712
+ return { ...base, planned: reqs.length, done: reqs.filter(r => DONE.has(r.status)).length, ...(s.status === "completed" ? { fromSnapshot: false } : {}) };
3703
3713
  };
3704
3714
  const completed = sprints.filter(s => s.status === "completed").map(row);
3705
3715
  const withWork = completed.filter(s => s.planned > 0);
3706
3716
  const avg = withWork.length ? withWork.reduce((n, s) => n + s.done, 0) / withWork.length : null;
3717
+ const rate = withWork.length ? withWork.reduce((n, s) => n + s.done / s.planned, 0) / withWork.length : null;
3707
3718
  return {
3708
3719
  completedSprints: completed,
3709
3720
  averageDonePerCompletedSprint: avg === null ? null : Math.round(avg * 10) / 10,
3721
+ averageCompletionRate: rate === null ? null : Math.round(rate * 100) / 100,
3710
3722
  openSprints: sprints.filter(s => s.status !== "completed").map(row),
3711
3723
  unplannedApprovedRequirements: active.filter(r => r.status === "approved" && !r.sprintId).length,
3712
3724
  };
@@ -3714,7 +3726,7 @@ const mcpTools = [
3714
3726
  },
3715
3727
  {
3716
3728
  name: "propose_sprint_plan",
3717
- description: "Save a sprint plan as a PENDING proposal instead of applying it. A project member reviews it in qa-tools (Sprints → Plan proposals), selects rows and approves — Claude can never approve. Use when the user isn't in this conversation, or asks to decide later. Only approved, functional requirements; each row targets an existing sprintId OR a newSprintRef from newSprints. The whole proposal is refused if any row can't be planned.",
3729
+ description: "Save a sprint plan as a PENDING proposal instead of applying it. A project member reviews it in qa-tools (Sprints → Plan proposals), selects rows and approves — Claude can never approve. Use when the user isn't in this conversation, or asks to decide later. Only functional requirements: approved ones without a sprint, or — as a move — approved or in-progress ones in an overdue sprint (they keep status and assignee). Each row targets an existing sprintId OR a newSprintRef from newSprints. The whole proposal is refused if any row can't be planned.",
3718
3730
  inputSchema: mcpSchema({
3719
3731
  goal: mcpStr("What the plan optimises for, e.g. 'Release 4.0 by Nov 18'"),
3720
3732
  summary: mcpStr("Short rationale: capacity used, dependency order, risks"),
@@ -3753,9 +3765,51 @@ const mcpTools = [
3753
3765
  description: "Requirements deliberately left out, with why",
3754
3766
  items: { type: "object", properties: { key: mcpStr("Requirement key"), reason: mcpStr("Why") }, required: ["key", "reason"], additionalProperties: false },
3755
3767
  },
3768
+ testProtocols: {
3769
+ type: "array",
3770
+ description: "One manual test protocol per target sprint: only tests a person must perform (you can't verify them yourself). Each test's requirementKey must be planned in that sprint by this proposal. Approved together with the proposal.",
3771
+ items: {
3772
+ type: "object",
3773
+ properties: {
3774
+ name: mcpStr("Protocol name, e.g. 'Release 4.1 — manual tests'"),
3775
+ sprintId: mcpStr("Existing sprint ID (or use newSprintRef)"),
3776
+ newSprintRef: mcpStr("ref of a sprint in newSprints"),
3777
+ sections: {
3778
+ type: "array",
3779
+ description: "Sections of manual tests",
3780
+ items: {
3781
+ type: "object",
3782
+ properties: {
3783
+ title: mcpStr("Section title"),
3784
+ tests: {
3785
+ type: "array",
3786
+ items: {
3787
+ type: "object",
3788
+ properties: {
3789
+ id: mcpStr("Test id, e.g. M-1"),
3790
+ name: mcpStr("What is tested"),
3791
+ steps: mcpStr("Steps a person follows"),
3792
+ expected: mcpStr("Expected result"),
3793
+ purpose: mcpStr("Why a person must perform this, e.g. 'real phone camera', 'SMS must actually arrive', 'visual check'"),
3794
+ requirementKey: mcpStr("Key of the requirement it verifies"),
3795
+ },
3796
+ required: ["name", "steps", "expected", "purpose", "requirementKey"],
3797
+ additionalProperties: false,
3798
+ },
3799
+ },
3800
+ },
3801
+ required: ["title", "tests"],
3802
+ additionalProperties: false,
3803
+ },
3804
+ },
3805
+ },
3806
+ required: ["name", "sections"],
3807
+ additionalProperties: false,
3808
+ },
3809
+ },
3756
3810
  }, ["items"]),
3757
3811
  run: async (a) => {
3758
- const r = await mcpCall("createPlanProposal", { projectId: a.projectId, ...mcpPick(a, ["goal", "summary", "items", "newSprints", "omitted"]) });
3812
+ const r = await mcpCall("createPlanProposal", { projectId: a.projectId, ...mcpPick(a, ["goal", "summary", "items", "newSprints", "omitted", "testProtocols"]) });
3759
3813
  return { ...r, next: "Pending. A project member approves or rejects it in qa-tools under Sprints → Plan proposals." };
3760
3814
  },
3761
3815
  },
@@ -3902,6 +3956,49 @@ const mcpTools = [
3902
3956
  return { updated: a.itemId, fields: Object.keys(u) };
3903
3957
  },
3904
3958
  },
3959
+ {
3960
+ name: "create_test_protocol",
3961
+ description: "Create a sprint's manual test protocol after a plan was approved in this conversation (sprint.ai-planning-manual-tests). Only tests a person must perform — what you can verify yourself belongs in automated tests in the code. It is saved for review (pending_review); a project member approves it under Test protocols, never you.",
3962
+ inputSchema: mcpSchema({
3963
+ sprintId: mcpStr("Sprint ID the protocol belongs to"),
3964
+ name: mcpStr("Protocol name, e.g. 'Release 4.1 — manual tests'"),
3965
+ sections: {
3966
+ type: "array",
3967
+ description: "Sections of manual tests",
3968
+ items: {
3969
+ type: "object",
3970
+ properties: {
3971
+ title: mcpStr("Section title"),
3972
+ tests: {
3973
+ type: "array",
3974
+ items: {
3975
+ type: "object",
3976
+ properties: {
3977
+ id: mcpStr("Test id, e.g. M-1"),
3978
+ name: mcpStr("What is tested"),
3979
+ steps: mcpStr("Steps a person follows"),
3980
+ expected: mcpStr("Expected result"),
3981
+ purpose: mcpStr("Why a person must perform this, e.g. 'real phone camera', 'SMS must actually arrive', 'visual check'"),
3982
+ requirementKey: mcpStr("Key of the requirement it verifies"),
3983
+ },
3984
+ required: ["name", "steps", "expected", "purpose", "requirementKey"],
3985
+ additionalProperties: false,
3986
+ },
3987
+ },
3988
+ },
3989
+ required: ["title", "tests"],
3990
+ additionalProperties: false,
3991
+ },
3992
+ },
3993
+ }, ["sprintId", "name", "sections"]),
3994
+ run: async (a) => {
3995
+ for (const sec of a.sections) for (const t of sec.tests || []) {
3996
+ if (!String(t.purpose || "").trim()) throw new McpToolError(`Test "${t.name}" needs a purpose saying why a person must perform it`);
3997
+ }
3998
+ const r = await mcpCall("uploadTemplate", { projectId: a.projectId, sprintId: a.sprintId, name: a.name, sections: a.sections });
3999
+ return { ...r, next: "Pending review. A project member approves it in qa-tools under Test protocols." };
4000
+ },
4001
+ },
3905
4002
  {
3906
4003
  name: "list_templates",
3907
4004
  description: "List test templates (test protocols) and their review status.",
@@ -3974,16 +4071,18 @@ Follow these steps in order:
3974
4071
 
3975
4072
  1. Gather facts, don't guess: list_sprints, sprint_velocity, list_epics, list_requirements (status approved, plus anything already planned in open sprints).
3976
4073
  2. Draft a plan. Only requirements are planned — never create backlog items as tasks. Rules:
3977
- - Only status=approved, functional requirements without a sprint are candidates. Non-functional (compliance) requirements are continuous — never plan them. Never touch completed sprints or requirements already in one.
4074
+ - Only status=approved, functional requirements without a sprint are candidates. Non-functional (compliance) requirements are continuous — never plan them. Never touch completed sprints or the requirements in them. Requirements in other sprints stay where they are, except carry-over from overdue sprints (below).
3978
4075
  - An epic's requirements never go into an earlier sprint than the requirements of the epics it dependsOn.
3979
4076
  - Order by priority (1 first), then epic priority.
3980
- - Per sprint, plan roughly averageDonePerCompletedSprint requirements (from sprint_velocity), counting what is already planned there. If there is no history, say so and propose a conservative number.
4077
+ - Per sprint, plan roughly averageDonePerCompletedSprint requirements (from sprint_velocity), counting what is already planned there. If there is no history, say so and propose a conservative number. Mention averageCompletionRate (the share of planned requirements that usually gets done) in the proposal.
4078
+ - Carry-over: a sprint is overdue when its end date (releaseDate) is before today and it is not completed. Requirements in an overdue sprint that are approved or in progress are candidates to MOVE to an open sprint; they keep their status and assignee, and the reason names the overdue sprint. Never move requirements out of a sprint that has not passed its end date.
3981
4079
  - If the requirements don't fit in the existing sprints, propose new sprints (name + end date) — don't create them yet.
3982
- 3. Present the proposal as a table: sprint | requirement key | title | reason (priority / epic dependency / capacity). Also list what you deliberately left out and why, and any dependency conflicts you found.
4080
+ 3. Present the proposal as a table: sprint | requirement key | title | reason (priority / epic dependency / capacity). Show moves out of overdue sprints as their own rows, marked as moves, separate from newly planned requirements. Also list what you deliberately left out and why, and any dependency conflicts you found.
3983
4081
  4. STOP and ask the user: approve here, or save it as a proposal to decide later in qa-tools? Change nothing before that. Apply any adjustments the user asks for and show the table again.
3984
4082
  - If nobody is there to answer (an unattended run), or the user chooses "later": call propose_sprint_plan with the same rows, and report the result. Do not apply anything yourself.
3985
4083
  5. After approval in this conversation: create_sprint for any new sprints, then update_requirement with sprintId for each planned requirement. Report each change and any refusal verbatim — never retry a refused change in a different way.
3986
- 6. End with get_sprint_items for each affected sprint so the user can see the result.`,
4084
+ 6. Manual tests, per sprint: draft a test protocol with the tests a person must perform because you can't verify them yourself — look and feel, real mobile devices, e-mail/SMS actually arriving, BankID/Freja, printing/PDF, flows between several parties. Each test has requirementKey (a requirement planned in that sprint) and a purpose saying why a person must do it. What you can verify yourself goes into automated tests in the code, not here. Show the tests with the plan. With propose_sprint_plan, pass them as testProtocols (approved together with the proposal). After approval in the conversation, save each with create_test_protocol (pending review — a member approves it). A sprint with nothing that needs a person gets no protocol; say so.
4085
+ 7. End with get_sprint_items for each affected sprint so the user can see the result.`,
3987
4086
  },
3988
4087
  {
3989
4088
  name: "daily_agenda_run",