kimal3 0.7.0 → 0.9.0

package/skill/en/commands/k3plan.md

@@ -41,7 +41,7 @@ not needed any more — the state is in the app. You can delete it." You do not
 **What the output means** (example, made-up values):
 
 ```
-Spec 2026-09-23-content-planner · Content planner as a page (plan/2026-09-23-content-planner-page-spec.md)
+Spec 2026-09-23-content-planner · Content planner as a page (plan/2026-09-23-content-planner.md)
   US-1 · built · round 1 · Create posts
   US-2 · in progress · round 1 · Move posts in the calendar
 Noted topic T-3: Export as PDF
@@ -98,7 +98,7 @@ count `US-1`, `US-2` … yourself in their order.
 **The state of each story (`stand`):**
 - `offen` — nothing built yet.
 - `in_arbeit` — partly built, or a finding is open.
-- `gebaut` — built. The app sets the date; plus a `testen` sentence (section 4).
+- `gebaut` — built. The app sets the date; plus a `testen` text (section 4).
 - `weggelassen` — deliberately not built, `grund` is required (rule 8). Only if the spec or the
   person decided so — never on your own to tidy up. If in doubt: leave it `offen` and ask in the
   report.
@@ -110,8 +110,9 @@ Run the counter-check of each criterion **wherever you can**: the project's guar
 
 - `bestanden` (passed) — **only** if the counter-check ran in this session and showed the
   expected result. Never from memory, never from last time, never because the code "looks right".
-- `gescheitert` (failed) — it ran and showed something else. That is a finding (rule 1); the app
-  then puts the story and its spec under "In progress".
+- `gescheitert` (failed) — it ran and showed something else. That is a finding (rule 1): the story
+  then carries ⚠ and sits under "In progress" while a session is working on it, otherwise under
+  "Open" — its spec does not move to "Your test".
 - `offen` (not run) — everything that did not run: needs a browser, a sign-in, real data or a
   person. Reading only counts if the criterion says something about the file itself (a file
   exists, a text is there as written) — reading does not prove a behaviour.
@@ -122,7 +123,11 @@ built or checked (the spec is then under "Your test"). Until then the app calls
 already passed "Checked by Claude". Say in the report what is missing so the counter-check can
 run.
 
-**The `testen` sentence** (on every `gebaut` story, at most 1000 characters) is a guide for someone without technical knowledge. It says where to find it, what to do, what must appear, how to notice it is wrong. A command only if there is no other way - then say where to type it (in Claude Code in the project folder, with `!` in front) and put it in backticks. Without a command: "In the app open 'Metrics' and click the post from 14 Oct - it says '4,210 seen'. If a cell is empty, say 'Doesn't work'." With a command: "In Claude Code in the project folder type `! node wortzaehler.js beispiel.txt` - five lines appear, at the top 'der (4)'. If an error message appears, say 'Doesn't work'." If the sentence is missing, the app shows: "Claude didn't write down how to test this".
+**The `testen` text** (on every `gebaut` story, at most 1000 characters) is a guide for someone without technical knowledge. If the story sits in a spec with the box "How you test it", you take it from there, word for word; if the box is missing, you write it yourself. **One line per step** — where to find it, what to do, what must appear —, **without** the box heading, and **last** the line "Doesn't work if: …". In the JSON you separate the lines with `\n`: a real line break inside the text breaks the JSON, and `kimal3 plan report` cannot read the report. If the text is longer than 1000 characters, shorten the steps — never cut off in the middle of a sentence; the line "Doesn't work if: …" must stay at the end. A command only if there is no other way - then say where to type it (in Claude Code in the project folder, with `!` in front) and put it in backticks. If the text is missing, the app shows: "Claude didn't write down how to test this".
+
+**Checking is work.** Before you check a story with pending counter-checks (column "Claude test pending") against the code, you report it as `in_arbeit` **with** the session (so without `--no-session`) **and with `"pruefen": true`**: while you check, the dot at the project glows, but the card doesn't come into discussion — without the field the blue frame would wander through every spec you check. After the check you report the result (`gebaut`, or `in_arbeit` with a finding — every `in_arbeit` report from `/k3plan` carries `"pruefen": true`). Stories under "Your test" or "Done" you do **not** report again during the reconciliation, even if you look through them: `in_arbeit` followed by `gebaut` sets their build date to today, and every report shows the label "changed" and, with two sessions, the ⚠ "changed at the same time". What stays unfinished at the end of `/k3plan`, you report with `--no-session` (section 6).
+
+**How a spec is built.** If you find a spec while checking that is not built like this, say so in the report — you do not rewrite it. A story in it sits in four boxes: **User story** (the title names the person's goal) · **Acceptance criterion** (with counter-check) · **How you test it** (numbered steps, below them "Doesn't work if: …") · **Technical note**.
 
 **Findings** (`befunde`): only **open** ones. `quelle: "claude"` for something the story promises
 and doesn't do, and that no criterion covers. `seit`: the date the finding came up. A `befunde`
@@ -133,7 +138,7 @@ just the new one. If the field is missing, the list stays as it is.
 - It starts at `1` and **never** goes down; if a report has no `runde`, it stays.
 - **Raise it by exactly 1** when a story with a finding from the person (`quelle: "mensch"`) has
   been fixed since (Git history, and the counter-checks pass now): then `befunde: []`,
-  `stand: "gebaut"`, `runde` + 1, a new `testen` sentence. The person tests again. If it is
+  `stand: "gebaut"`, `runde` + 1, a new `testen` text. The person tests again. If it is
   unclear whether it was fixed: leave the finding and ask in the report.
 - **Also raise it** if you changed a **confirmed** story in a way the person would notice — their
   old "Works" no longer applies (rule 7).
@@ -143,11 +148,11 @@ just the new one. If the field is missing, the list stays as it is.
 
 The app shows them to the person in exactly this wording ("How planning stays short"):
 
-1. **A problem does not become a new card.** If a story doesn't hold what it promises — Claude's check fails or you say "Doesn't work" — the problem (finding) is attached to that story and its spec goes back to "In progress".
+1. **A problem does not become a new card.** If a story doesn't hold what it promises — Claude's check fails or you say "Doesn't work" — the problem (finding) is attached to that story. It stays in "Open" until someone works on it.
 2. **Only what nobody promised is new. It goes into the inbox, which has five places.**
-3. **Claude sorts every topic at the next check (`/k3plan`):** as a new story in a spec, as a finding on a story, or dropped with a reason. There is no "later". What happened to it is shown under "Sorted in by Claude".
+3. **Claude sorts every topic at the next check (`/k3plan`):** as a new story in a spec, as a finding on a story, or dropped with a reason. There is no "later".
 4. **Nothing stays in the inbox longer than 14 days.**
-5. **At most one spec in progress at once** ("In progress" and "Claude test pending" together). Finish it before starting the next.
+5. **At most one spec in progress at once** ("In progress" and "Claude test pending" together). "In progress" means: a Claude session is working on it right now. Finish it before starting the next.
 6. **At most five stories wait for your test.** If there are more, Claude starts nothing new until you have tested.
 7. **Done means checked twice:** Claude tried everything itself, and you said "Works" — for exactly this version.
 8. **A spec is only closed when every story is done or deliberately left out** — with a reason. There is no silent remainder.
@@ -155,8 +160,8 @@ The app shows them to the person in exactly this wording ("How planning stays sh
 **What you do with them** (every time a report, section 6):
 
 - **Rule 1 — every `doesn't work` from `kimal3 plan`:** if the story still exists, report it with
-  the person's sentence as a finding (`quelle: "mensch"`, `seit: "<today>"`) and
-  `stand: "in_arbeit"`, and right behind it in the same list `uebernommen` with the number:
+  the person's sentence as a finding (`quelle: "mensch"`, `seit: "<today>"`),
+  `stand: "in_arbeit"` and `"pruefen": true`, and right behind it in the same list `uebernommen` with the number:
   `{ "art": "uebernommen", "rueckmeldung": 12, "antwort": "Finding on US-2" }`. If it has already
   been fixed since, raise `runde` by 1 instead, with `befunde: []` and `stand: "gebaut"`
   (section 4). If the story no longer exists, the `antwort` says why. ⚠️ Without a finding from
@@ -177,10 +182,9 @@ The app shows them to the person in exactly this wording ("How planning stays sh
     `dropped: public holidays are already in the calendar tool.`
 
   For a note from the app (`#13 · Topic`), the answer goes into an `uebernommen` report as **one
-  sentence** (the app shows it under "Recently sorted" as `<note> → <answer>`); so write it
-  **without** an arrow at the start. A `Noted topic` of yours you sort with an `eingeordnet`
-  report (key, text as above, answer) — the app takes it out of the topics and shows it under
-  "Recently sorted" for 14 days. Name how it was sorted in the report too.
+  sentence**, **without** an arrow at the start. A `Noted topic` of yours you sort with an `eingeordnet`
+  report (key, text as above, answer) — the app takes it out of the topics.
+  The page doesn't show the answer; so name how it was sorted in the report.
 - **Rule 4:** because you sort everything at every `/k3plan`, nothing stays long. A topic that has
   been waiting more than 14 days is sorted now **in any case**.
 - **Rules 5 and 6 — don't start a new spec** while another spec is in progress (one of its
@@ -188,7 +192,7 @@ The app shows them to the person in exactly this wording ("How planning stays sh
   criterion or with no criteria at all), or while more than five stories are waiting for the person's test (`gebaut`, all
   passed, no finding, not yet confirmed — **and** no story of their spec keeps the spec in progress: only then
   is it under "Your test", and only then does the app count the story). **Tell the person what to test instead** — with the
-  `testen` sentences. If you sort a topic in as a new story in a spec, you do not start that spec
+  `testen` texts. If you sort a topic in as a new story in a spec, you do not start that spec
   with it: it stays `offen`, and the spec does not count as in progress.
 - **Rule 7:** only the person sets "Done", with "Works" in the app; a report has no field for it.
   You only keep the round stable (section 4).
@@ -196,46 +200,60 @@ The app shows them to the person in exactly this wording ("How planning stays sh
 
 ## 6. The reports
 
-A report is a JSON object, several are a list. It goes through the input to `kimal3 plan report --no-session`;
+A report is a JSON object, several are a list. It goes through the input to `kimal3 plan report`;
 the program sets the time itself, and the project comes from the folder note
-`plan/projekt.json`. Checking is not working — this way no dot lights up on the board.
+`plan/projekt.json`. Checking is work — reported with the session, the dot on the board glows while you check; `"pruefen": true` on every `in_arbeit` report keeps the card out of discussion meanwhile.
 
 ```
-echo '[ … ]' | kimal3 plan report --no-session
+echo '[ … ]' | kimal3 plan report
 ```
 
-(In PowerShell: `'[ … ]' | kimal3 plan report --no-session`. For long texts, use a file.) The examples are
+(In PowerShell: `'[ … ]' | kimal3 plan report`. For long texts, use a file.) The examples are
 made up.
 
+**At the very end** you report the stories that stay unfinished (in progress, a finding open) once more —
+in their **own** call with `--no-session`, separate from the list of the finished ones: a mixed list
+without the flag ties the unfinished story to the session too, and the dot keeps glowing. With the flag
+the plan state stays `in_arbeit`, but the dot stops glowing while the window stays open — on the board the
+story then sits under "Open" as started.
+
+```
+echo '[ … ]' | kimal3 plan report --no-session
+```
+
 **A spec** — when checking, and when stories are added:
 
 ```json
-{ "art": "spec", "schluessel": "2026-10-24-test-month", "titel": "Test month",
+{ "art": "spec", "schluessel": "2026-10-24-test-month-design", "titel": "Test month",
   "datei": "docs/superpowers/specs/2026-10-24-test-month-design.md",
   "stories": [ { "schluessel": "US-1", "titel": "The test month starts" },
                { "schluessel": "US-2", "titel": "The test month ends" },
                { "schluessel": "US-3", "titel": "Export of the test month" } ] }
 ```
 
+Leave out `wartet_auf_lesen` here: if the field is missing, the label "Waiting for you to read" stays as it is. It is set
+and removed when you hand a spec to the person to read and they approve it (coach, section 3.6) — the same goes for the report
+`gespraech`; `/k3plan` sends none.
+
 **A story** — one deviation, one entry. Built, with a counter-check:
 
 ```json
-{ "art": "story", "spec": "2026-10-24-test-month", "story": "US-1", "stand": "gebaut",
+{ "art": "story", "spec": "2026-10-24-test-month-design", "story": "US-1", "stand": "gebaut",
   "kriterien": [ { "text": "If Sabine starts on 1 Nov, the test month ends on 30 Nov.", "gegenprobe": "bestanden" } ],
-  "testen": "In the app open 'Test month' and click \"Start\" - below it says 'Ends on 30 Nov'. If it shows another date, say 'Doesn't work'." }
+  "testen": "1. In the app open 'Test month'.\n2. Click Start.\n3. Below it says 'Ends on 30 Nov'.\nDoesn't work if: it shows another date." }
 ```
 
 With an open finding (here from you; `quelle: "mensch"` only for the person's sentence):
 
 ```json
-{ "art": "story", "spec": "2026-10-24-test-month", "story": "US-2", "stand": "in_arbeit",
+{ "art": "story", "spec": "2026-10-24-test-month-design", "story": "US-2", "stand": "in_arbeit", "pruefen": true,
   "befunde": [ { "text": "On 30 Nov the reminder mail the spec promises is missing.", "quelle": "claude", "seit": "2026-10-23" } ] }
 ```
 
 Deliberately left out (`grund` is required):
 
 ```json
-{ "art": "story", "spec": "2026-10-24-test-month", "story": "US-3", "stand": "weggelassen", "grund": "The spec drops the export." }
+{ "art": "story", "spec": "2026-10-24-test-month-design", "story": "US-3", "stand": "weggelassen", "grund": "The spec drops the export." }
 ```
 
 **A topic** (rule 2), **sorting a topic of yours** (rule 3), **handing on a response from the
@@ -264,6 +282,8 @@ send it again. `2` — no longer signed in: tell the person `kimal3 login`; the
 | `Response 12 doesn't exist in this project or is listed twice …` | Only numbers from `kimal3 plan`, each once. |
 | `Response 12 ("…") is marked as handled, but US-2 has no finding from you …` | Report the story with the finding `quelle: "mensch"` first (rule 1) — or `runde` + 1 if it has been fixed — then `uebernommen`. |
 | `The plan can't be read: <place> …` | Correct the named place in the report (length, `grund` on `weggelassen`, duplicate key). |
+| `The “in discussion” report needs the chat it comes from.` | Report again with the session, not with `--no-session`. |
+| `Another chat is discussing this card right now.` | Do nothing: another chat carries the discussion. |
 | `The report arrived, but the text of <file> didn't …` | Send the report again — sending twice does no harm. If the text no longer fits (over 300 KB), tell the person. |
 | `The reports are saved, but not fully recorded yet.` | Send again — sending twice does no harm. |
 | `The planning saved in the app is damaged …` | Tell the person. `kimal3 plan upload --overwrite` replaces the planning with a whole file `plan/stand.json` — **only after their explicit yes.** |
@@ -276,7 +296,7 @@ message suggests it.
 **At most five lines**, without jargon — and nothing about the reports themselves:
 
 - what became **done** (confirmed since last time),
-- what is **waiting for their test** (only stories from specs under "Your test") — with the `testen` sentence so they can start right away,
+- what is **waiting for their test** (only stories from specs under "Your test") — with the `testen` text so they can start right away,
 - what was decided in the **inbox** (each topic with its answer),
 - a **warning** if rule 5 or 6 is broken: "Test first …" instead of a new story,
 - the **link** from `View: …`.

package/skill/en/commands/k3show.md

@@ -60,7 +60,9 @@ workbench) · “The project folder is nested too deeply for the recorder …”
 
 If the session is in the workbench, say **that first**, in one sentence: the recording belongs in
 a project, and you'll suggest one in a moment. Then explain in at most five short sentences what
-happens, and ask **one** question:
+happens, and ask **one** question. **Word for word: the first sentence of that explanation is
+exactly this one: “You show me the task once and talk while you do it.”** Don't open with anything
+else and don't reword it (only the workbench sentence above may come before it); the rest follows as written:
 
 > “You show me the task once and talk while you do it. I record the screen, sound, clicks and
 > keys. It stays on your computer. Before I read any of it, I'll ask you. Which task do you want

package/skill/en/commands/k3wrapup.md

@@ -21,21 +21,30 @@ and skip it — no filler.
 - **Reconcile the board — only in a project folder that has a project in the app** (otherwise skip
   it and say nothing). `kimal3 plan` shows the state the app knows; hold it against what really
   happened today. What is done and whose counter-checks ran in this session is `gebaut` with
-  criteria and a `testen` sentence; what was started and isn't done stays `in_arbeit`; what came
-  up today and no spec promises goes in as a `thema`. Report only what differs from that state, in
+  criteria and a `testen` text; what was started and isn't done stays `in_arbeit` — and goes into its **own** call `kimal3 plan report --no-session`, separate from the list of the finished ones (a mixed list without the flag ties the unfinished story to the session too, and the dot keeps glowing although the window is merely open); what came
+  up today and no spec promises goes in as a `thema`. Report only what differs from that state: the finished ones in
   one list with `kimal3 plan report` (format and exit codes: the coach, section 3.6, and
   `/k3plan`, section 6; what an exit code means is in `~/.claude/skills/kimal3/SKILL.md`):
 
   ```json
-  [ { "art": "story", "spec": "2026-10-24-test-month", "story": "US-1", "stand": "gebaut",
+  [ { "art": "story", "spec": "2026-10-24-test-month-design", "story": "US-1", "stand": "gebaut",
       "kriterien": [ { "text": "If Sabine starts on 1 Nov, it ends on 30 Nov.", "gegenprobe": "bestanden" } ],
-      "testen": "Open /test-month and click Start - below it says Ends on 30 Nov." },
-    { "art": "story", "spec": "2026-10-24-test-month", "story": "US-2", "stand": "in_arbeit" } ]
+      "testen": "1. Open /test-month.\n2. Click Start.\n3. Below it says Ends on 30 Nov.\nDoesn't work if: it shows another date." } ]
+  ```
+
+  And what stays unfinished, separately, with the flag:
+
+  ```json
+  [ { "art": "story", "spec": "2026-10-24-test-month-design", "story": "US-2", "stand": "in_arbeit" } ]
+  ```
+
+  ```
+  echo '[ … ]' | kimal3 plan report --no-session
   ```
 
   On success you say nothing about it. If you mention the board in the wrap-up (step 6), then only
   what did **not** work (a refusal, or kept because the app was not reachable). The dot at the
-  project on the project page stays as long as the window is open; when the person closes it, it
+  project on the project page stays for work in progress, as long as the window is open; when the person closes it, it
   is gone in under a second.
 
 ## 2. Update the status file — and tidy it up