qatools-cli 1.2.27 → 1.2.29

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.
package/context-sync.js CHANGED
@@ -56,6 +56,7 @@ function renderToolsSection() {
56
56
  "### qa-tools tools for this project",
57
57
  "- Code exists that no requirement covers (built before qa-tools, or on the side): `qatools baseline-prompt` — reconstruct requirements from the code; a member approves them as built.",
58
58
  "- Users should be able to request features and vote (whether or not the app already has a page for it): `qatools requests-integration-prompt` — requests, votes and comments reach qa-tools and their status (accepted / planned / released / declined) goes back to the app. See what has arrived: `qatools feature-requests`.",
59
+ "- A release is done: `qatools release-notes-prompt` — draft release notes for the app's users (only what they notice, no technical details), save with `qatools release-notes-draft`; a member publishes them.",
59
60
  "- Something more important must go into a sprint in progress: propose a swap (MCP `propose_sprint_plan` swaps) instead of overfilling it; a member approves.",
60
61
  "",
61
62
  ].join("\n");
@@ -136,6 +137,11 @@ function requestsIntegrationPrompt(projectName) {
136
137
  " Replies from the project's members come back with author \"team\". comment and comments also work for requests the",
137
138
  " app syncs itself (A), with the app's own id. Votes on synced requests are refused (409) — their votes come from the app.",
138
139
  "",
140
+ "What is new (both A and B): published release notes, newest first — show them to the users on a \"What's new\" page:",
141
+ ' { "action": "releaseNotes", "limit": 3 }',
142
+ ' → { "releases": [ { "release": "Release 4.1", "releaseDate": "2026-11-18", "publishedAt": "…", "notes": "- You can now …" } ] }',
143
+ " The notes are plain text with short points (- …), written for users and published by a member. Drafts never come back.",
144
+ "",
139
145
  "Errors: 401 missing key, 403 wrong or revoked key, 400 bad body (e.g. no userId, no title, title over 300",
140
146
  "characters), 404 unknown request, 409 vote on a synced request, 429 more than 600 calls a minute from one server.",
141
147
  "",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "qatools-cli",
3
- "version": "1.2.27",
3
+ "version": "1.2.29",
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
@@ -1093,6 +1093,53 @@ program
1093
1093
  process.exit(0);
1094
1094
  });
1095
1095
 
1096
+ // releases.release-notes: release notes for the app's users — Claude drafts, a member publishes in the sprint view
1097
+ program
1098
+ .command("release-notes-prompt")
1099
+ .description("Print what a release delivered and how to write release notes for the app's users (default: the latest completed release)")
1100
+ .option("-s, --sprint <id|name>", "The release (sprint id or name)")
1101
+ .option("--project <id>", "Target project ID (overrides default)")
1102
+ .option("-e, --email <email>", "Login email")
1103
+ .option("-p, --password <password>", "Login password")
1104
+ .action(async (options) => {
1105
+ await authenticate(options);
1106
+ const projectId = options.project || getCredentials()?.projectId;
1107
+ if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
1108
+ try {
1109
+ const { data } = await httpsCallable(functions, "getReleaseNotesPrompt")({ projectId, sprintId: options.sprint || "" });
1110
+ console.log(data.prompt);
1111
+ process.exit(0);
1112
+ } catch (e) {
1113
+ console.error("Failed to get the release-notes prompt:", e.message);
1114
+ process.exit(1);
1115
+ }
1116
+ });
1117
+
1118
+ program
1119
+ .command("release-notes-draft")
1120
+ .description("Save a draft of a release's notes for the app's users. A member edits and publishes it in the sprint view.")
1121
+ .requiredOption("-s, --sprint <id|name>", "The release (sprint id or name)")
1122
+ .requiredOption("-f, --file <path>", "Text or markdown file with the notes")
1123
+ .option("--project <id>", "Target project ID (overrides default)")
1124
+ .option("-e, --email <email>", "Login email")
1125
+ .option("-p, --password <password>", "Login password")
1126
+ .action(async (options) => {
1127
+ let text;
1128
+ try { text = fs.readFileSync(options.file, "utf8"); }
1129
+ catch (e) { console.error(`Could not read ${options.file}: ${e.message}`); process.exit(1); }
1130
+ await authenticate(options);
1131
+ const projectId = options.project || getCredentials()?.projectId;
1132
+ if (!projectId) { console.error("No project configured. Run: qatools setup, or pass --project <id>"); process.exit(1); }
1133
+ try {
1134
+ const { data } = await httpsCallable(functions, "saveReleaseNotesDraft")({ projectId, sprintId: options.sprint, text });
1135
+ console.log(`Draft saved on ${data.sprintId}. A member edits and publishes it in the sprint view${data.published ? " (the published notes stay until then)" : ""}.`);
1136
+ process.exit(0);
1137
+ } catch (e) {
1138
+ console.error("Draft not saved:", e.message);
1139
+ process.exit(1);
1140
+ }
1141
+ });
1142
+
1096
1143
  // requirements.baseline-from-code: reconstruct requirements for what is already built
1097
1144
  program
1098
1145
  .command("baseline-prompt")
@@ -2210,7 +2257,7 @@ program
2210
2257
  console.error(" Evidence-driven status: cite a concrete verification before claiming resolved.");
2211
2258
  console.error(" Examples:");
2212
2259
  console.error(" --evidence \"Test SPRINT-1.2 passed in session abc123, item appeared in sprint list\"");
2213
- console.error(" --evidence \"Reproduced bug then re-ran: input=10, expected=50, actual=50 (file.ts:42)\"");
2260
+ console.error(" --evidence \"Reproduced the fault then re-ran: input=10, expected=50, actual=50 (file.ts:42)\"");
2214
2261
  console.error(" --evidence \"No test applies — pure docs change in CHANGELOG.md\"");
2215
2262
  console.error("");
2216
2263
  console.error(" Min 10 chars. If you cannot articulate the verification, use status=ready_for_test instead.");
@@ -2775,7 +2822,7 @@ basis for being a substitute** — you're just guessing what their rules are.
2775
2822
 
2776
2823
  ## When you're tempted to skip the chain
2777
2824
 
2778
- You will be tempted. The user will be impatient. The bug will look obvious.
2825
+ You will be tempted. The user will be impatient. The cause will look obvious.
2779
2826
  You will think "I'll just fix it and they can verify".
2780
2827
 
2781
2828
  That is exactly the failure mode qa-tools was built to prevent. The substitute
@@ -2789,7 +2836,7 @@ step if they were doing it manually? If no, you can't either.
2789
2836
 
2790
2837
  - qa-loop.md — the mechanics of the loop
2791
2838
  - qa-evidence-first.md — the core principle (cite, don't guess)
2792
- - qa-numerical-verification.md — for algorithmic bugs
2839
+ - qa-numerical-verification.md — for algorithmic and numerical errors
2793
2840
  - qa-developer.md — implementation guidance
2794
2841
  `,
2795
2842
  "qa-loop.md": `---
@@ -2809,7 +2856,7 @@ Requirement → Build → Test → Backlog → Fix → Verify
2809
2856
  1. **Requirement defined** — Acceptance criteria (Given/When/Then) and negative scenarios. Each requirement has a semantic key (e.g. \`auth.login-trial\`).
2810
2857
  2. **Feature built** — AI or human implements the feature. Traceable to the requirement via requirementKey.
2811
2858
  3. **Test runs** — Tests are generated from acceptance criteria. Each test links to a requirementKey.
2812
- 4. **Backlog updates automatically** — Failed tests create backlog items (bugs). Each item is traceable to requirement, feature, and test.
2859
+ 4. **Backlog updates automatically** — Failed tests create backlog items (deviations, AVV). Each item is traceable to requirement, feature, and test.
2813
2860
  5. **AI analyzes and fixes** — AI identifies root cause: is it the code or the requirement? Fixes code or suggests requirement adjustment.
2814
2861
  6. **Retest verifies** — The loop closes only when the requirement is verified.
2815
2862
 
@@ -2879,7 +2926,7 @@ qatools sprint-create --name "Release 3.2" --start 2026-05-01 --end 2026-05-28
2879
2926
  - A requirement MUST be expressible in Given/When/Then. If it can't → it's an epic or too vague
2880
2927
  - Every requirement MUST link to an epic via epicKey
2881
2928
  - DEPENDENCY HYGIENE: Before creating or modifying epic dependencies, ALWAYS run \`qatools epics\` to review the full dependency graph. Validate: (1) no circular deps, (2) existing deps still make sense, (3) the graph stays minimal — remove deps that are no longer needed. The model evolves — stale dependencies are worse than missing ones.
2882
- - Every test, bug, and fix MUST trace back to a requirementKey
2929
+ - Every test, signal and fix MUST trace back to a requirementKey
2883
2930
  - Never create duplicate requirements — run \`qatools requirement-keys\` first
2884
2931
  - The loop runs until every requirement is verified
2885
2932
  - BACKLOG = SIGNALS ONLY: AVV (deviation from req), GAP (missing req), DEF (technical issue), IMP (idea). Never create requirements as backlog items. Backlog items are observations — requirements are what you build from.
@@ -3056,12 +3103,12 @@ When planning a sprint, draft one such protocol per sprint (MCP: testProtocols i
3056
3103
  `,
3057
3104
 
3058
3105
  "qa-test-analyst.md": `---
3059
- description: Analyze failed test sessions and fix bugs. Use when test sessions are pending analysis.
3106
+ description: Analyze failed test sessions and fix the deviations they found. Use when test sessions are pending analysis.
3060
3107
  ---
3061
3108
 
3062
3109
  # QA-Tools: Test Analyst
3063
3110
 
3064
- You analyze test sessions and fix bugs found during testing.
3111
+ You analyze test sessions and fix the deviations found during testing.
3065
3112
 
3066
3113
  ## Workflow
3067
3114
 
@@ -3074,7 +3121,7 @@ You analyze test sessions and fix bugs found during testing.
3074
3121
  3. For each FAILED test:
3075
3122
  - Analyze root cause: is it the code or the requirement?
3076
3123
  - Determine verdict: bugg, troligen-db, testprotokoll, design, ux, ej-aktuell, kräver-genomgång
3077
- - Fix the bug if possible (fixStatus: "fixed", list filesChanged)
3124
+ - Fix the deviation if possible (fixStatus: "fixed", list filesChanged)
3078
3125
  - If the requirement is wrong, set verdict to "testprotokoll"
3079
3126
 
3080
3127
  4. Upload analysis:
@@ -3193,26 +3240,26 @@ Say "I'm unsure" — that's better than guessing. Suggest what evidence would re
3193
3240
 
3194
3241
  ## Specialized skills
3195
3242
 
3196
- There is a specific skill for **algorithmic and numerical** bugs: \`qa-numerical-verification.md\`. Read it when you're fixing a formula or any code where the bug is "wrong number" rather than "wrong structure".
3243
+ There is a specific skill for **algorithmic and numerical** errors: \`qa-numerical-verification.md\`. Read it when you're fixing a formula or any code where the error is "wrong number" rather than "wrong structure".
3197
3244
 
3198
- If you encounter a different recurring bug class that needs its own verification pattern (UI regressions, race conditions, data integrity, etc.), create a NEW specific skill (\`qa-<class>-verification.md\`) rather than expanding this file or building a monolithic "fix-checklist". The pattern is: principle here, specific category in its own skill, CLI enforces evidence regardless of category. Don't build a generic checklist for hypothetical categories — let real biting cases drive the need.
3245
+ If you encounter a different recurring class of errors that needs its own verification pattern (UI regressions, race conditions, data integrity, etc.), create a NEW specific skill (\`qa-<class>-verification.md\`) rather than expanding this file or building a monolithic "fix-checklist". The pattern is: principle here, specific category in its own skill, CLI enforces evidence regardless of category. Don't build a generic checklist for hypothetical categories — let real biting cases drive the need.
3199
3246
  `,
3200
3247
  "qa-numerical-verification.md": `---
3201
- description: How to verify algorithmic and numerical bug fixes. Read this when fixing a formula, calculation, or any code where the bug is "wrong number" rather than "wrong structure".
3248
+ description: How to verify fixes of algorithmic and numerical errors. Read this when fixing a formula, calculation, or any code where the error is "wrong number" rather than "wrong structure".
3202
3249
  ---
3203
3250
 
3204
3251
  # Numerical & Algorithmic Verification
3205
3252
 
3206
- Most evidence-first examples deal with structural bugs (NullReferenceException, wrong redirect, race condition). Algorithmic bugs are different — the code runs without crashing, it just produces the wrong number.
3253
+ Most evidence-first examples deal with structural errors (NullReferenceException, wrong redirect, race condition). Algorithmic errors are different — the code runs without crashing, it just produces the wrong number.
3207
3254
 
3208
- This skill is for those bugs. The verification pattern is non-negotiable.
3255
+ This skill is for those errors. The verification pattern is non-negotiable.
3209
3256
 
3210
3257
  ## Before you start — entry-point checklist
3211
3258
 
3212
3259
  Stop here and answer these BEFORE writing any verification code:
3213
3260
 
3214
- - [ ] Which input or test case actually triggers the bug? (Not "the system" — name a specific input.)
3215
- - [ ] Does that input have non-zero, non-default values for the field the bug touches? (If everything is 0 or NULL, multiplying by anything gives the same result — the input cannot discriminate buggy from fixed code.)
3261
+ - [ ] Which input or test case actually triggers the error? (Not "the system" — name a specific input.)
3262
+ - [ ] Does that input have non-zero, non-default values for the field the error touches? (If everything is 0 or NULL, multiplying by anything gives the same result — the input cannot discriminate buggy from fixed code.)
3216
3263
  - [ ] If your input is non-discriminating: change it, or pick a different input. Never proceed with "the data doesn't show it".
3217
3264
  - [ ] Where will you write the expected and actual values? Answer: in the --evidence flag when you set status. If the values are large, also save them to a file you reference in evidence ("see /tmp/verify-2026-04-08.txt").
3218
3265
  - [ ] Can you compute the expected value by hand from the formula in under 60 seconds? If not, the formula is too complex for this verification — break it into pieces and verify each.
@@ -3223,11 +3270,11 @@ If any answer is "I don't know", stop and ask. Don't guess.
3223
3270
 
3224
3271
  1. **Trivialize the input.** Pick values that make the formula readable. Set multipliers to 1, set inputs to round numbers (10, 100), set toggles to known states.
3225
3272
  2. **Compute the expected value by hand.** Write down the formula, plug in the trivialized inputs, get the expected number. Show your work.
3226
- 3. **Run the same input through the system.** Use whatever entry point the bug lives in — CLI, API, UI, test harness. Capture the actual output.
3273
+ 3. **Run the same input through the system.** Use whatever entry point the error lives in — CLI, API, UI, test harness. Capture the actual output.
3227
3274
  4. **Compare with tolerance.** For floats, exact equality is fragile. Use a tolerance (e.g. abs(actual - expected) < 0.001) and document it.
3228
3275
  5. **Cite both numbers in evidence.** When you set status=tested, the --evidence flag must contain both the expected and actual value, plus the input that produced them.
3229
3276
 
3230
- ## What "evidence" looks like for numerical bugs
3277
+ ## What "evidence" looks like for numerical errors
3231
3278
 
3232
3279
  ❌ "Fixed the formula in calculation.ts"
3233
3280
  ❌ "User confirmed the value looks right now"
@@ -3235,19 +3282,19 @@ If any answer is "I don't know", stop and ask. Don't guess.
3235
3282
 
3236
3283
  ✅ "Input: mass=10 kg, rate=5 kr/kg, alpha=0. Expected = 10*5 = 50. Actual = 50.0 (calc.ts:142). Diff < 0.001."
3237
3284
  ✅ "Input: temp=20°C, time=3600s. Expected = 20*3600/1000 = 72 kWh. Actual = 72.0 (sim.py:88)."
3238
- ✅ "Trivialized: set kr_per_kg=1 to inspect the structure. Expected = mass*1 = mass = 10. Actual = 10.0. Now bumped kr_per_kg=5: expected=50, actual=50. Original bug was (1+alpha)*prod*rate*T which gave 132 for the same input."
3285
+ ✅ "Trivialized: set kr_per_kg=1 to inspect the structure. Expected = mass*1 = mass = 10. Actual = 10.0. Now bumped kr_per_kg=5: expected=50, actual=50. Original fault was (1+alpha)*prod*rate*T which gave 132 for the same input."
3239
3286
 
3240
3287
  ## Why this matters
3241
3288
 
3242
- The difference between "I fixed it" and "I verified it" is the difference between a fix that holds and a fix that creates the next bug. For numerical code, "looks right" is not verification — the formula can be wrong by a constant factor and look fine until production.
3289
+ The difference between "I fixed it" and "I verified it" is the difference between a fix that holds and a fix that creates the next error. For numerical code, "looks right" is not verification — the formula can be wrong by a constant factor and look fine until production.
3243
3290
 
3244
3291
  ## Specific traps
3245
3292
 
3246
3293
  ### 1. The dataset doesn't have a discriminating input
3247
- If your test data has kr_per_kg = 0 for everything, multiplying by anything gives 0. The bug in the multiplication is invisible. **Fix: change the dataset or create a new one** with values that would produce different results between the buggy and fixed formula. Never skip verification with "the data doesn't show it".
3294
+ If your test data has kr_per_kg = 0 for everything, multiplying by anything gives 0. The error in the multiplication is invisible. **Fix: change the dataset or create a new one** with values that would produce different results between the buggy and fixed formula. Never skip verification with "the data doesn't show it".
3248
3295
 
3249
3296
  ### 2. Off-by-constant errors
3250
- The bug formula (1+alpha) * prod * rate * T happens to equal the correct mass * rate when alpha=0 AND prod*T = mass. If your test input satisfies both, both formulas pass. **Fix: pick inputs where the two formulas diverge.**
3297
+ The wrong formula (1+alpha) * prod * rate * T happens to equal the correct mass * rate when alpha=0 AND prod*T = mass. If your test input satisfies both, both formulas pass. **Fix: pick inputs where the two formulas diverge.**
3251
3298
 
3252
3299
  ### 3. Sign errors and unit mismatches
3253
3300
  mg/MJ vs kg/MWh differ by 10^9 / 3600 ≈ 277,777x. A "small refactor" can introduce this and pass type checks. **Fix: include unit conversion in the trivialized expected calc.**
@@ -3517,7 +3564,7 @@ const BUILTIN_SKILLS = [
3517
3564
  { name: "qa-test-analyst", description: "Analyze test results, identify root causes, create backlog items." },
3518
3565
  { name: "qa-release-manager", description: "Sprint planning and release verification." },
3519
3566
  { name: "qa-evidence-first", description: "Core principle — never speculate, always cite evidence. Applies to ALL work." },
3520
- { name: "qa-numerical-verification", description: "How to verify algorithmic and numerical bug fixes." },
3567
+ { name: "qa-numerical-verification", description: "How to verify fixes of algorithmic and numerical errors." },
3521
3568
  ];
3522
3569
 
3523
3570
  const skillCmd = program
@@ -4502,6 +4549,18 @@ const mcpTools = [
4502
4549
  }, ["answers"]),
4503
4550
  run: async (a) => mcpCall("applyNewAppAnswers", { projectId: a.projectId || getCredentials()?.projectId, answers: a.answers, overwrite: !!a.overwrite }),
4504
4551
  },
4552
+ {
4553
+ name: "release_notes_prompt",
4554
+ description: "What a release delivered and how to write release notes for the app's users (releases.release-notes): only what users notice, in their words, no keys or technical details. Default: the latest completed release.",
4555
+ inputSchema: mcpSchema({ sprintId: mcpStr("The release: sprint id or name (default: latest completed)") }),
4556
+ run: async (a) => (await mcpCall("getReleaseNotesPrompt", { projectId: a.projectId, sprintId: a.sprintId || "" })).prompt,
4557
+ },
4558
+ {
4559
+ name: "save_release_notes_draft",
4560
+ description: "Save a draft of a release's notes for the app's users. Refused if it names requirement keys, signal ids or commits. A member edits and publishes it in the sprint view — you never publish.",
4561
+ inputSchema: mcpSchema({ sprintId: mcpStr("The release: sprint id or name"), text: mcpStr("The notes: short points in the users' language") }, ["sprintId", "text"]),
4562
+ run: async (a) => mcpCall("saveReleaseNotesDraft", { projectId: a.projectId, sprintId: a.sprintId, text: a.text }),
4563
+ },
4505
4564
  {
4506
4565
  name: "baseline_prompt",
4507
4566
  description: "Procedure for reconstructing requirements for what is already built (requirements.baseline-from-code), with the project's language, its epics and all existing requirements. Use when code exists that qa-tools has no requirements for.",