kimal3 0.6.5 → 0.8.0

package/skill/en/commands/k3plan.md

@@ -1,122 +1,104 @@
 ---
-description: Check the specs against the code and upload the planning to the app
+description: Check the specs against the code and report every deviation to the board in the app
 ---
 
 <!-- kimal3:erzeugt — this file is maintained by `kimal3 skill install` and
      overwritten on every update. Your own changes will be lost; if you want
      to keep them, copy the file under a different name. -->
-# Checking and uploading the planning
+# Checking and reporting the planning
 
 ## 1. What for
 
-You check the user stories in this project's specs against the code and upload **only the
-result** to the app — never the code. There, on the project page (tab "Planning"), the person
-sees what is open, what is waiting for their test and what is done, and gives a verdict with
-"Works" or "Doesn't work".
+You check the user stories in this project's specs against the code and **report every deviation
+individually** to the app — never the code, and since version 0.7.0 no whole file any more. There,
+on the project page (tab "Planning", the board), the person sees what is open, what is waiting for
+their test and what is done, and gives a verdict with "Works" or "Doesn't work".
 
-Work through the sections in order. You need the rules (section 5) and the file format
-(section 6) from section 2 onwards — read them first. What an exit code of `kimal3` means is in
+Work through the sections in order. You need the rules (section 5) and the reports (section 6)
+from section 2 onwards — read them first. What an exit code of `kimal3` means is in
 **`~/.claude/skills/kimal3/SKILL.md`, section "Exit codes"**; this file does not repeat it.
 
-🔑 **`/k3plan` checks, sorts and uploads — it builds nothing.** Whatever needs fixing is
+🔑 **`/k3plan` checks, sorts and reports — it builds nothing.** Whatever needs fixing is
 attached to the story as a finding afterwards; building happens when the person says so.
 
-## 2. Fetch the responses
+## 2. Fetch the state
 
-Work in the **project folder** (where the specs and the code are). The file is always called
-`plan/stand.json`, relative to that folder.
+Work in the **project folder** (a folder directly inside `workbench-…/projects/`). The state is in
+the app, not in a file:
 
 ```
 kimal3 plan
 ```
 
-**If you get `There's no plan/stand.json in this folder.`**, it is the first time (or you are in
-the wrong folder — check that first):
-
-1. `kimal3 project list` — look for the project this is about. If there is **no** matching one,
-   ask the person which one is meant and suggest `/k3project <what you built>`
-   (German: `/k3projekt`): without an entry in the success profile there is no project page.
-   Stop there, don't invent anything.
-2. Create `plan/stand.json` with the name **exactly as the list writes it**:
-
-   ```json
-   {
-     "format": 1,
-     "projekt": "LinkedIn Content App",
-     "projekt_id": null,
-     "basis": null,
-     "geprueft_am": "2026-10-21T22:10:00+02:00",
-     "specs": [],
-     "themen": [],
-     "uebernommen": []
-   }
-   ```
-
-   (Name and time are an example.) The field names are German and stay German. `kimal3 plan
-   upload` enters `projekt_id` and `basis` itself after the first upload — **leave them at
-   `null`**.
-3. Run `kimal3 plan` again.
+**If you get `This folder isn't connected to a project in the app yet.`**, create the project:
+`kimal3 project connect` (the coach, section 3.6, says what to do there), then `kimal3 plan`
+again. If you get `This isn't a project folder …`, you are in the wrong folder — check that first
+and report nothing.
+
+**If the folder has a `plan/stand.json`**, tell the person **once**: "The file plan/stand.json is
+not needed any more — the state is in the app. You can delete it." You do not delete it yourself.
 
 **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)
+  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
 #12 · doesn't work · 2026-09-23-content-planner / US-2 (round 1): When dragging, it jumps to Tuesday
 #13 · Topic: The calendar should show public holidays
 Confirmed: 2026-09-23-content-planner / US-1 (round 1)
 View: https://app.kimal3.de/projekt/…
 ```
 
+- `Spec <key> · <title> (<file>)` and below it one line per story, `<key> · <state> · round n ·
+  <title>` — the state the app knows. **The keys from here are binding** (section 3).
+- `Noted topic <key>: …` — a topic that **Claude** noted earlier. → Rule 3.
 - `#12 · doesn't work · <spec> / <story> (round n): <sentence>` — the person tested the story and
   it doesn't hold. → Rule 1 in section 5. You need the number later for `uebernommen`.
 - `#13 · Topic: <sentence>` — something new they noted in the app. → Rule 3.
 - `Confirmed: …` — for these stories they said "Works" in **this** round; they are done. You
   never need to hand on a "Works".
 - `View: …` — the link to the planning. Keep it for the report.
+- `No planning in the app yet.` — this is the first time; carry on with section 3, every spec is new.
 - `No open responses.` — nothing to hand on; carry on with section 3.
 
-**Refusals:**
-- `No project is called "…". Your projects: … Enter the name in plan/stand.json exactly like
-  that.` — copy the matching name **word for word** from the list into `"projekt"`. If two could
-  fit, ask.
-- `Several of your projects are called "…" (ids: …).` — ask the person which one is meant and
-  enter its id as `"projekt_id"`.
-- `The project number in plan/stand.json belongs to none of your projects.` — the number comes from
-  a copied folder or a deleted project. Set `"projekt_id"` to `null` (the line stays, the field is
-  required); then kimal3 searches by name. This is the **only** case in which you change
-  `projekt_id` yourself.
-- `The plan can't be read: plan/stand.json doesn't contain a valid JSON object.` — repair the
-  brackets or commas in the file.
+**Refusals** are a whole sentence on the error output (exit code `1`): read it, tell the person
+what it says, and don't repeat blindly. If `kimal3 plan` returns `3` (app not reachable), try once
+more later.
 
 ## 3. Find the specs
 
 In the project folder, look in **`docs/superpowers/specs/`**, **`plan/`** and **`docs/specs/`**
 for Markdown files with user stories ("As … I want … so that …", often `US-1`, `US-2`, with
-acceptance criteria and a counter-check). `plan/stand.json` itself, status notes and task lists
-are not specs.
+acceptance criteria and a counter-check). `plan/stand.json`, `plan/projekt.json`, status notes
+and task lists are not specs.
 
-One entry in `specs` per spec, one entry in `stories` per user story, one entry in `kriterien`
-per acceptance criterion (in short, at most 500 characters: starting point → action → result).
+One `spec` report per spec with its stories, one entry in `kriterien` per acceptance criterion
+(in short, at most 500 characters: starting point → action → result).
 
 🔴 **The keys are binding.** The app ties every "Works" and "Doesn't work" to spec key + story
-key + round. If a spec or story is already in `plan/stand.json`, **keep its key unchanged** — a
-renamed key makes the person's verdict disappear. New: spec key = file name without `.md`; story
-key = the number from the spec (`US-3`); if the spec doesn't number them, count `US-1`, `US-2` …
-yourself in their order.
+key + round. If a spec or story is already in the output of `kimal3 plan`, **keep its key
+unchanged** — a renamed key makes the person's verdict disappear. New: spec key = file name
+without `.md`; story key = the number from the spec (`US-3`); if the spec doesn't number them,
+count `US-1`, `US-2` … yourself in their order.
 
 - `titel`: the heading of the spec or the story. `datei`: the path of the spec in the project
-  folder (relative, ends in `.md`; otherwise `null`). `kimal3 plan upload` reads the **text** of the spec from
-  this file and sends it along — it does not read paths outside the project folder.
+  folder (relative, ends in `.md`; otherwise `null`). The mod `kimal3-plan` uploads the **text** of
+  the spec when the file is written, and `kimal3 plan report` brings it along if the file was
+  written before the report — it does not read paths outside the project folder.
 - The story key is **the same as in the heading of the spec**, where the spec numbers its stories
   (`### US-3 · …` → `US-3`): the app finds the story in the spec text through this key.
 - A spec without stories goes in with `"stories": []`; mention it in the report.
 - Limits: at most 50 specs, 60 stories per spec, 400 altogether. If there are more, ask the
   person which specs belong in.
+- A story you can no longer find in the spec you **do not remove** — a report cannot delete a
+  story. Report it as `weggelassen` with a reason if the spec decided so.
 
 **The state of each story (`stand`):**
 - `offen` — nothing built yet.
-- `in_arbeit` — partly built, or a finding is open. `gebaut_am` is then `null`.
-- `gebaut` — built. `gebaut_am`: the date on which **this round** was finished (`YYYY-MM-DD`);
-  plus a `testen` sentence (section 4).
+- `in_arbeit` — partly built, or a finding is open.
+- `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.
@@ -128,29 +110,35 @@ 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.
 
-⚠️ A story with an `offen` criterion is shown under "Claude test pending", and the person can't
-test it yet. Say in the report what is missing so the counter-check can run.
+⚠️ A story with an `offen` criterion is shown under "Claude test pending" — and its whole spec with it.
+The person tests a spec as a whole: they only get buttons once no story of the spec is still being
+built or checked (the spec is then under "Your test"). Until then the app calls the stories that
+already passed "Checked by Claude". Say in the report what is missing so the counter-check can
+run.
+
+**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`): while you check, the dot at the project glows. After the check you report the result (`gebaut`, or `in_arbeit` with a finding). 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).
 
-**The `testen` sentence** (on every `gebaut` story, at most 1000 characters) names **the address
-or the command** and **what must be visible there**, for example: "Start `npm run dev`, open
-http://localhost:3000/calendar and drag the post from Monday to Wednesday — it is then on
-Wednesday." Without it the app shows: "Claude didn't write down how to test this".
+**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 — if it is
-already in the file, it keeps its old date.
+and doesn't do, and that no criterion covers. `seit`: the date the finding came up. A `befunde`
+field in a report **replaces** the story's list — so send all findings that are still open, not
+just the new one. If the field is missing, the list stays as it is.
 
 **The round** (`runde`) ties a verdict to a build — like a stamp on one version of a document:
-- It starts at `1` and **never** goes down.
+- 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"`, a new `gebaut_am`, 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).
@@ -160,195 +148,159 @@ already in the file, it keeps its old date.
 
 The app shows them to the person in exactly this wording ("How planning stays short"):
 
-1. **A finding is not a new card.** If a story doesn't hold what it promises — Claude's check fails or you say "Doesn't work" — the 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 `/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 "Recently sorted".
+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's checks passed, and you said "Works" — for exactly this version.
+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.
 
-**What you do with them:**
+**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, attach the
-  person's sentence to it as a finding (`{ "text": "<their sentence>", "quelle": "mensch",
-  "seit": "<today>" }`), `stand: "in_arbeit"`, `gebaut_am: null`. If it has already been fixed
-  since, raise the round by 1 and set `befunde: []` instead (section 4). Plus in `uebernommen`:
-  `{ "rueckmeldung": 12, "antwort": "Finding on US-2" }`. If the story no longer exists, the
-  `antwort` says why. ⚠️ Without a finding from `mensch` and without a higher round, the server
-  refuses the upload.
+- **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:
+  `{ "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
+  `mensch` and without a higher round, the app refuses the handover.
 - **Rule 2 — something new:** what you notice while checking, or what the person says in the
-  conversation, and what **no** spec promises goes into `themen`:
-  `{ "schluessel": "T-1", "text": "…", "quelle": "claude" | "mensch", "seit": "<today>" }`.
-  Take the next free number, counting `eingeordnet` too (a key stays taken there for 14 days).
-  The five places are shared by `themen` and the open notes from the app.
-- **Rule 3 — sort:** every `Topic` from `kimal3 plan` **and** every topic already in `themen` from
-  earlier is sorted **now** — one of three:
+  conversation, and what **no** spec promises, you report as a `thema`. Take the next free number
+  (`T-4` after `T-3`) — and remember that a sorted topic keeps its key for 14 days: if the app
+  says a key appears twice, take the next number. The five places are shared by your topics and
+  the open notes from the app.
+- **Rule 3 — sort:** every `Topic` from `kimal3 plan` **and** every `Noted topic` is sorted
+  **now** — one of three:
   - **new story:** write it into the spec it belongs to (user story, acceptance criterion with
-    counter-check) and into `plan/stand.json` with `stand: "offen"`. If no spec fits, ask where it
-    goes. Answer: `new story US-7 in "Content planner"`.
+    counter-check), and report the spec with the new story (`stand` stays `offen`; the new one is
+    enough, the old ones stay). If no spec fits, ask where it goes. Answer:
+    `new story US-7 in "Content planner"`.
   - **finding on a story:** as in rule 1. Answer: `finding on US-2 in "Content planner"`.
   - **dropped:** answer `dropped: <reason in one sentence>`, for example
     `dropped: public holidays are already in the calendar tool.`
 
-  For a note from the app, the answer goes into `uebernommen` as **one sentence** (the app shows
-  it under "Recently sorted" as `<note> → <answer>`); so write it **without** an arrow at the
-  start. A topic from the file you take out of `themen` and write it with its answer into
-  `eingeordnet`: `{ "schluessel": "T-4", "text": "<text as in themen>", "antwort": "<one
-  sentence>", "am": "<today>" }` — the app shows it under "Recently sorted" for 14 days. Entries
-  whose `am` is more than 14 days ago you take out at the same time. Name how it was sorted in the
-  report too.
-- **Rule 4:** because you sort everything at every `/k3plan`, nothing stays long. A topic with
-  `seit` more than 14 days ago is sorted now **in any case**.
+  For a note from the app (`#13 · Topic`), the answer goes into an `uebernommen` report as **one
+  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
   stories is `in_arbeit`, has a finding or a failed counter-check, or is `gebaut` with an `offen`
   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). **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
+  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` 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; the file has no field for it.
+- **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).
 - **Rule 8:** `weggelassen` only with a `grund` (section 3).
 
-## 6. The file
+## 6. The reports
 
-`plan/stand.json` is under Git. Example, shortened:
+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 work — reported with the session, the dot on the board glows while you check.
 
-```json
-{
-  "format": 1,
-  "projekt": "LinkedIn Content App",
-  "projekt_id": null,
-  "basis": null,
-  "geprueft_am": "2026-10-21T22:10:00+02:00",
-  "specs": [
-    {
-      "schluessel": "2026-09-23-content-planner",
-      "titel": "Content planner as a page",
-      "datei": "plan/2026-09-23-content-planner-page-spec.md",
-      "stories": [
-        {
-          "schluessel": "US-2",
-          "titel": "Move posts in the calendar",
-          "stand": "gebaut",
-          "runde": 1,
-          "gebaut_am": "2026-10-21",
-          "kriterien": [
-            { "text": "Drag the post from Monday to Wednesday -> it is on Wednesday", "gegenprobe": "bestanden" }
-          ],
-          "befunde": [],
-          "testen": "Open /calendar and drag the post from Monday to Wednesday.",
-          "grund": null
-        }
-      ]
-    }
-  ],
-  "themen": [
-    { "schluessel": "T-1", "text": "The calendar should show public holidays", "quelle": "mensch", "seit": "2026-10-21" }
-  ],
-  "uebernommen": [
-    { "rueckmeldung": 12, "antwort": "Finding on US-2" }
-  ],
-  "eingeordnet": [
-    { "schluessel": "T-2", "text": "Export as PDF", "antwort": "dropped: the print button already does that.", "am": "2026-10-21" }
-  ]
-}
+```
+echo '[ … ]' | kimal3 plan report
 ```
 
-**The fields** — every one must be there, even if it is `null` or empty (only `eingeordnet` may
-be missing); the server refuses an unknown field (a typo like `"befund"`):
-
-- `format`: exactly `1`.
-- `projekt`: the name as in the app, 1–200 characters.
-- `projekt_id`, `basis`: `null` at first; after that `kimal3 plan upload` writes them — **never
-  change them by hand**. Only exception: the refusal "The project number in plan/stand.json
-  belongs to none of your projects." — then set `projekt_id` to `null` (section 2).
-- `geprueft_am`: now, with time zone (`date +%Y-%m-%dT%H:%M:%S%:z` in Bash, `Get-Date -Format
-  "yyyy-MM-ddTHH:mm:sszzz"` in PowerShell).
-- `specs[]`: `schluessel` (unique, 1–80 characters), `titel` (1–200), `datei` (path or `null`),
-  `stories[]`.
-- `stories[]`: `schluessel` (unique within its spec), `titel`, `stand` (`offen` · `in_arbeit` ·
-  `gebaut` · `weggelassen`), `runde` (1–999), `gebaut_am` (`YYYY-MM-DD` for `gebaut`, otherwise
-  `null`), `kriterien[]`, `befunde[]`, `testen` (sentence or `null`), `grund` (required for
-  `weggelassen`, otherwise `null`).
-- `kriterien[]`: `{ "text", "gegenprobe": "bestanden" | "gescheitert" | "offen" }`, at most 30
-  per story.
-- `befunde[]`: `{ "text", "quelle": "claude" | "mensch", "seit": "YYYY-MM-DD" }` — open ones only,
-  at most 20.
-- `themen[]`: `{ "schluessel", "text", "quelle", "seit" }`, at most 50 (the inbox has five places,
-  rule 2).
-- `uebernommen[]`: `{ "rueckmeldung": <number from kimal3 plan>, "antwort": "<one sentence>" }`.
-  `kimal3 plan upload` empties it itself after uploading.
-- `eingeordnet[]`: `{ "schluessel", "text", "antwort": "<one sentence>", "am": "YYYY-MM-DD" }`, at
-  most 50 — topics from `themen` that you have sorted (rule 3). A key is never in `themen` and
-  `eingeordnet` at the same time.
-- The whole file: at most 300 KB.
-
-## 7. Upload
-
-First the dry run — it checks everything and saves nothing:
+(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
 ```
-kimal3 plan upload --dry-run
+
+**A spec** — when checking, and when stories are added:
+
+```json
+{ "art": "spec", "schluessel": "2026-10-24-test-month", "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" } ] }
 ```
 
-`Dry run: would upload 9 stories and mark 2 responses as handled. Nothing was saved.` (numbers as
-an example). **Compare the second number** with the open responses from `kimal3 plan`: if it is
-smaller, you forgot one — it would stay in the app under "Waiting for Claude".
+**A story** — one deviation, one entry. Built, with a counter-check:
 
-Then:
+```json
+{ "art": "story", "spec": "2026-10-24-test-month", "story": "US-1", "stand": "gebaut",
+  "kriterien": [ { "text": "If Sabine starts on 1 Nov, the test month ends on 30 Nov.", "gegenprobe": "bestanden" } ],
+  "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",
+  "befunde": [ { "text": "On 30 Nov the reminder mail the spec promises is missing.", "quelle": "claude", "seit": "2026-10-23" } ] }
 ```
-kimal3 plan upload
+
+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." }
 ```
 
-It worked if you see `✓ Planning for "…" uploaded: … stories, … waiting for your test.` and
-`View: …`; the first time also `projekt_id and basis are now in plan/stand.json.` The CLI has
-entered `projekt_id` and `basis` and emptied `uebernommen` — leave the file like that. Tell the
-person that `plan/stand.json` has changed and belongs in the next commit.
+**A topic** (rule 2), **sorting a topic of yours** (rule 3), **handing on a response from the
+person** (rules 1 and 3):
+
+```json
+{ "art": "thema", "schluessel": "T-4", "text": "The calendar could show public holidays" }
+{ "art": "eingeordnet", "schluessel": "T-3", "text": "Export as PDF", "antwort": "dropped: the print button can already do that." }
+{ "art": "uebernommen", "rueckmeldung": 12, "antwort": "Finding on US-2" }
+```
 
-After that comes a line `Spec texts uploaded: 1 of 3. Without text: …` — the text of the specs goes up too.
-A spec without text is a **hint, not a failure** (exit code `0`): tell the person which specs are in
-the brackets and what to do (correct the path in `datei`; over 300 KB cannot be uploaded; with
-"all spec texts together larger than 4 MB" no single file is too large — the largest stay out
-until the rest fits).
+**What the program returns:** on success it is silent (`0`) — and **so are you**: don't tell the
+person that you reported. `1` — the app refused or the input was unreadable; the sentence on the
+error output says why. Reports it doesn't name arrived. `3` — the app is not reachable; the report
+is **kept** and goes along with the next command (`kimal3 plan send` sends it right away) — don't
+send it again. `2` — no longer signed in: tell the person `kimal3 login`; the report is kept.
 
-**Refusals — read the message, fix it, dry run, again:**
+**Refusals — read the message, fix it, send again:**
 
-| The message starts with | What you do |
+| Message starts with | What you do |
 |---|---|
-| `The plan can't be read: <place> …` | Repair that place (`specs[0].stories[2].stand`) in the file. |
-| `No project is called …` · `Several of your projects are called …` · `The project number in plan/stand.json belongs to none of your projects.` | As in section 2. For the project number you may set `projekt_id` to `null` — only here. |
-| `<spec> / <story> has round 1, round 2 is already saved.` | The file is older than the saved state. Set the round to the saved value — never lower. |
-| `Response 12 doesn't exist in this project or is listed twice …` | Only numbers from `kimal3 plan`, each one once. |
-| `Response 12 ("…") is marked as handled, but US-2 has no finding from you …` | Attach the finding with `quelle: "mensch"` to the story (rule 1) — or raise the round by 1 if it has been fixed. |
-| `The app has a newer plan (uploaded …).` | Another working copy has uploaded. **Do not overwrite.** Tell the person and ask whether you should first fetch that state (Git) and check again. `kimal3 plan upload --overwrite` **only after their explicit yes.** |
-| `The planning saved in the app is damaged …` | Here too, `--overwrite` **only after their yes.** |
-| `The planning is saved, but the responses aren't marked as handled yet.` | Run `kimal3 plan upload` **unchanged** once more — that is harmless, the CLI has already entered `basis` and left `uebernommen` in place. |
-| ``The plan is saved, but the spec texts are not. Run `kimal3 plan upload` again.`` | Run `kimal3 plan upload` **unchanged** once more — the plan is already in the app, the CLI has entered `basis`. |
-| `⚠ The planning is saved, but plan/stand.json couldn't be updated. Enter it yourself: …` | Write exactly these values into the file. |
-| `… couldn't be loaded just now` / `… couldn't be saved just now` | Try once more; if it still fails, tell the person. |
-
-🔴 **`--overwrite` replaces what someone else uploaded.** Never on your own decision, not even
-when the message suggests it.
-
-## 8. Report to the person
-
-**At most five lines**, without jargon:
-
-- what was **done** (confirmed since last time),
-- what is **waiting for their test** — with the `testen` sentence, so they can start right away,
+| `The report on <story> from <time> arrived too late …` | Another session or the person changed the story afterwards. **Do not send again.** `kimal3 plan` shows today's state; report only what is still missing. |
+| `The spec … doesn't exist in this project yet.` · `… has no story …` | Report the spec with its stories first (section 6, "A spec"), then the story. |
+| `Report no. 2 can't be read (meldung).` | The report has a wrong field or lacks one — hold it against the examples above. Nothing was sent. |
+| `<spec> / <story> has round 1, round 2 is already saved.` | Your round is older than the saved one. Send again with the saved one or higher — never lower. |
+| `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 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.** |
+
+🔴 **`--overwrite` replaces what others reported.** Never on your own decision, not even if the
+message suggests it.
+
+## 7. Report to the person
+
+**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` 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,
+- a **warning** if rule 5 or 6 is broken: "Test first …" instead of a new story,
 - the **link** from `View: …`.
 
 Example (made-up values):
 
 ```
 Done: US-1 "Create posts".
-Your test: US-2 - open /calendar and drag the post from Monday to Wednesday.
-Inbox: "The calendar should show public holidays" -> new story US-7 in "Content planner".
-Claude test pending: US-4 needs a browser I don't have here.
+Your test: US-2 — open /calendar and drag the post from Monday to Wednesday.
+Inbox: "The calendar should show public holidays" → new story US-7 in "Content planner".
+Claude test pending: US-4 needs a browser, which I don't have here.
 Planning: https://app.kimal3.de/projekt/…
 ```

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

@@ -18,6 +18,34 @@ and skip it — no filler.
 - Is it a Git repo? Then `git status` + `git diff --stat`: what was changed in this
   session? Summarise it in 1–2 sentences.
 - Not a Git repo? Say so briefly and offer to set one up (a safety net) — don't force anything.
+- **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` 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",
+      "kriterien": [ { "text": "If Sabine starts on 1 Nov, it ends on 30 Nov.", "gegenprobe": "bestanden" } ],
+      "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", "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 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
 The status file (`NEXT-STEPS.md` or `ROADMAP.md`) is the note for the next start. It is only