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 +6 -0
- package/package.json +1 -1
- package/qatools.js +81 -22
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.
|
|
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
|
|
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
|
|
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
|
|
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 (
|
|
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,
|
|
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
|
|
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
|
|
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
|
|
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**
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
3215
|
-
- [ ] Does that input have non-zero, non-default values for the field the
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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.",
|