k0-board 0.4.0 → 0.6.0

package/.claude/skills/k0-ultracode/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: k0-ultracode
+description: Runs a whole epic — or one story — as a manager with agents under it: it takes what the board already knows, cuts the plan into assignments, hands each one to an agent working in an isolated copy of the repository, brings the work back one piece at a time, and closes every story with the tests, a fresh pair of eyes and the counter-check before moving to the next. Use this skill when the user types "/k0-ultracode" or "/k0-ultracode K7", or says "run the whole epic", "take this and go", "do it with agents", "hand it to the manager", "fallo tutto tu", "porta avanti l'epica", "usa gli agenti", "vai fino in fondo". Do not use it to talk a story through (that is /k0-discuss), to write a plan and stop (/k0-plan), to do one story by hand in one session (/k0-work), or to push, tag or release anything (/commit-push-deploy).
+---
+
+# /k0-ultracode [key]
+
+One manager, several agents, and a board that says at every moment where the work is.
+
+`[key]` is an epic such as `K7` or a story such as `K42`. With no argument, the story is the one
+this session is attached to. With something that is not a key — a sentence, a file — there is
+nothing on the board yet, and §2 puts it there before anything else happens.
+
+Three words are used here and nowhere else in k0. The **manager** is you, this session. An
+**assignment** is one slice of a plan. An **agent** is a subagent that carries out exactly one
+assignment in a copy of the repository of its own. Agents never speak to the user: everything the
+user hears comes from the manager.
+
+## 1. Find what you were pointed at
+
+```bash
+PORT="${K0_PORT:-4319}"
+REPO="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)"; REPO="${REPO%/.git}"
+[ -d "$REPO" ] || REPO="$(git rev-parse --show-toplevel 2>/dev/null)"
+curl -sS --max-time 30 --get --data-urlencode "repo=$REPO" \
+  "http://127.0.0.1:$PORT/api/backlog" -o "$SCRATCH/k0-backlog.json"
+```
+
+`127.0.0.1`, not `k0.localhost`: browsers resolve that name by themselves, `curl` does not.
+`--get --data-urlencode`, not `?repo=$REPO`: a repository path with a space in it makes `curl`
+refuse the address outright, and one with a `#` in it quietly sends half. `$SCRATCH` is the
+session's scratch directory, and nothing is written outside it and the worktrees of §6.
+
+- `curl` cannot connect → the k0 server is not running. Say so (`k0-board start`, or the tray
+  icon → *Restart*) and **stop**.
+- `{"enabled": false}` → say in one line that the k0 backlog is switched off and **stop**.
+- `REPO` empty → this is not a git repository. Ask once which repository this belongs to and take
+  the path he gives.
+
+An epic key gives the epic and the stories under it, in the order the board already has them and
+with the dependencies it already knows. A story key gives one story. If two things could be meant,
+ask once, showing both.
+
+## 2. Nothing on the board yet
+
+A sentence said out loud, a document, an idea: it goes onto the board first, because everything
+after this reads the board and nothing else.
+
+- Something big — a feature, an area of the product → `/k0-epic`: its rounds, its decisions, its
+  tree of stories, approved before a line is written.
+- One thing he already knows he wants → `/k0-story`, and carry on here.
+
+Follow those skills rather than paraphrasing them. When they are done there is a key, and §3 starts
+on it.
+
+## 3. Ask once: how much rope, and how hard
+
+One `AskUserQuestion`, two questions, and **never a `preview` on an option** — the free-text box
+disappears when there is one, and this is the moment he is most likely to want it.
+
+**How much rope** — `interactive`, `checkpoint` or `autonomous`. **How hard** — `light`, `medium`
+(the default) or `hard`. What each one means, how many agents it allows at once, how many repair
+attempts it buys and where it stops is in `references/modes.md`. Read it now and hold it for the
+whole run; the path is relative to the folder this skill was loaded from.
+
+Say the answer back in one line — "autonomous, medium: three agents at a time, two repair
+attempts, and I come back when the epic is done or when something is genuinely stuck" — and write
+that same line into the Log of the epic, or of the story when there is no epic. That line is the
+contract, and §9 reads it back after a crash.
+
+## 4. One story at a time
+
+Stories are taken in the board's order, and a story whose dependencies are not `Done` waits for
+them. A story is finished — merged, tested, counter-checked — before the next one starts. On an
+epic that is the whole point: a mistake caught in the first story is a mistake the other six never
+inherit.
+
+For each story, §5 to §8, then a Log entry saying it is closed, then the next one.
+
+## 5. Decisions, a plan, and the cut
+
+```bash
+curl -sS --max-time 30 "http://127.0.0.1:$PORT/api/backlog/story/$STORY_ID" -o "$SCRATCH/k0-story.json"
+```
+
+`$STORY_ID` is the `id` of the story, not its key.
+
+- **No decisions** → the rounds of `../k0-discuss/references/rounds.md`, which is also where the
+  shape of a decision and the collision rule live. In `autonomous` only the questions that would
+  change the work get asked; the rest you settle yourself and write down as assumptions (§8), never
+  as decisions.
+- **No plan** → write one in the shape `/k0-plan` gives it: `## What you get`, then
+  `## Constraints — already decided` listing every standing decision verbatim **by `label`**, then
+  steps that each end with the labels they serve. Store it and move the story on:
+
+  ```bash
+  curl -sS --max-time 30 -X POST "http://127.0.0.1:$PORT/api/backlog/story/$STORY_ID/plan" \
+    -H 'content-type: application/json' -d @"$SCRATCH/k0-plan.json"      # {"text": "…"}
+  curl -sS --max-time 30 -X PATCH "http://127.0.0.1:$PORT/api/backlog/story/$STORY_ID" \
+    -H 'content-type: application/json' -d '{"state": "Planned"}'
+  ```
+
+- **The decisions that are still standing** are the constraints every agent works under. Leave out
+  any with `superseded_by` set, and call each one by its `label` and never by its number: an
+  inherited one is `K7·D3`, and the story may have a `D3` of its own saying something else entirely.
+
+Then cut the plan into **assignments**, and cut it by file:
+
+- two assignments that would write the same file are one assignment, or they are done one after the
+  other — never at the same time;
+- an assignment that cannot be described without naming another one is not ready to be cut;
+- where the repository's own `CLAUDE.md` asks for documentation with every change — k0's does — the
+  last assignment of every story is the documentation and the changelog line.
+
+One `TaskCreate` per assignment, in order, plus one for the merge and one for the counter-check;
+exactly one `in_progress` at a time. If `TaskCreate` is not among your tools, say so in one line and
+carry on with the Log alone — never call it again to see whether it has come back.
+
+Write the cut into the Log before an agent is spawned: what each assignment is, which files it
+owns, which of them run together. In `interactive` and `checkpoint`, show it and wait.
+
+## 6. The worktrees
+
+Every agent writes in a copy of the repository of its own, and the manager owns all of them.
+
+```
+<the branch you are on>
+└─ k0u-K42                the story's own branch      → $SCRATCH/k0u/K42
+   ├─ k0u-K42-a1          assignment 1                → $SCRATCH/k0u/K42-a1
+   └─ k0u-K42-a2          assignment 2                → $SCRATCH/k0u/K42-a2
+```
+
+```bash
+git -C "$REPO" worktree add -b "k0u-$KEY" "$SCRATCH/k0u/$KEY" HEAD
+git -C "$REPO" worktree add -b "k0u-$KEY-a1" "$SCRATCH/k0u/$KEY-a1" "k0u-$KEY"
+```
+
+From the branch you are on — not `main`, not `origin`. No `git pull`, no `git fetch`, no checking
+out anything else first: if the user is on a feature branch, that is the branch this work belongs
+to and the branch the merge goes back into.
+
+They live in the session's scratch directory rather than in `.claude/worktrees/`, which belongs to
+k0 and is swept by the server. They have no `.env` and no `node_modules`, and that is not an
+oversight: it is the physical reason an agent cannot start a server or run a suite even if it
+forgets it was told not to.
+
+k0's own `POST /api/backlog/worktree` is not used here. It records one worktree against one
+session, and `POST /api/backlog/story/:id/start` opens a real terminal window — on an epic of eight
+stories that would be eight windows. The board stays honest all the same, because the state and the
+Log are written by the manager.
+
+## 7. The agents
+
+One agent per assignment, `general-purpose`, on the model this session is already running. How many
+run at once is the number `references/modes.md` gave you in §3 and no more: a fourth agent waits for
+a free slot rather than starting.
+
+What an agent is handed and what it owes back is `references/agent-brief.md` — the assignment, the
+standing decisions verbatim by label, the path of its worktree as the only place on disk it may
+write, and the shape of its report. Read it before spawning the first one.
+
+An agent cannot ask the user anything. It comes back with its questions written down, and they are
+the manager's to answer: in `interactive` they go to the user as they arrive; in `checkpoint` they
+are held to the next stop; in `autonomous` you answer them yourself unless the answer would
+contradict a standing decision — that one always comes back to the user — and each answer becomes
+an assumption in the Log.
+
+An agent that comes back empty, or that says it could not do the assignment, is not retried on the
+spot. That is a repair, and repairs are counted and spent in §8.
+
+## 8. Back together, then the only things that are ever run
+
+The agents' branches come into the story's branch one at a time, in the order the assignments were
+cut:
+
+```bash
+git -C "$SCRATCH/k0u/$KEY" merge --no-ff "k0u-$KEY-a1"
+```
+
+A conflict here means the cut was wrong. In `interactive` and `checkpoint`: stop, show which files,
+let the user decide. In `autonomous`: resolve it only where the conflict is inside the files that
+assignment owned and a standing decision says which side wins; otherwise leave that assignment out,
+say so plainly, and carry on with the rest — the good work still goes in.
+
+Then the story goes into the branch the run started on:
+
+```bash
+git -C "$SCRATCH/k0u/$KEY" add -A && git -C "$SCRATCH/k0u/$KEY" commit -m "…"   # if anything is pending
+git -C "$REPO" merge --no-ff "k0u-$KEY"
+```
+
+One line, Conventional Commits, English, written from the diff, saying what changed for the person
+using this project rather than which function moved. The base repository must be clean first: if it
+is not, stop and say so rather than committing somebody else's work.
+
+**Never `git push`. Never a pull request.** Not with a flag, not because the branch tracks a remote,
+not to be helpful. What leaves this machine leaves it through `/commit-push-deploy`, and only when
+the user asks.
+
+Then, in the base repository and nowhere else:
+
+1. **The tests.** `npm test` in k0, and whatever the repository says its gate is anywhere else.
+   This is the only thing this skill ever runs, and it runs here because here the code on the disk
+   is the code that was merged. Inside a worktree it would be a green run against the wrong code.
+2. **A fresh pair of eyes.** An agent that wrote none of it reads this story's diff against the plan
+   and the standing decisions and tries to knock it down. On `hard`, two of them with a lens each —
+   one on the decisions, one on correctness — and a third asking what the plan forgot.
+3. **The repairs.** Red tests, or a finding worth acting on: one agent, in the base repository,
+   committing `fix: …`. Two attempts on `medium` and `hard`, one on `light`. After the last one,
+   stop. Say in one line what is still broken and leave everything else merged — work that passes
+   is not held hostage by work that does not.
+4. **The counter-check.** `/k0-verify` on this story: the state goes to `Review`, every standing
+   decision gets `kept`, `violated` or `na` with its evidence, and the run goes in one call. Do not
+   set `Done`: `Done` is the button the user presses, and nothing else may press it.
+
+Last, put the worktrees away — whatever happened, including after a failure:
+
+```bash
+git -C "$REPO" worktree remove --force "$SCRATCH/k0u/$KEY-a1"
+git -C "$REPO" branch -D "k0u-$KEY-a1"
+```
+
+A run that ends with a `k0u-*` branch still standing is a run that lied about being finished.
+
+## 9. Picking it up cold
+
+The Log is the state of this run and there is no second copy of it. Each of these gets an entry the
+moment it happens — on the story, and on the epic when a story closes:
+
+- the line from §3 saying which mode and how hard;
+- the cut into assignments, before any agent starts;
+- each assignment as it lands, with the files it touched;
+- each assumption taken alone;
+- the merge, the tests, the counter-check, and anything left out.
+
+So a session that runs out of context, or a terminal somebody closed, costs nothing but the
+assignment that was in flight. Running `/k0-ultracode` again on the same key reads the Log, says in
+one line where the last run got to, and starts from the first assignment that never landed. Nothing
+the Log records as merged is ever done twice.
+
+## 10. Close
+
+To the user, in his language, and nothing after it:
+
+**Cosa ho fatto** — what is different now, story by story: whether the tests were green, what the
+fresh pair of eyes said, how the counter-check came out.
+
+**Cosa resta a te** — the assumptions taken alone, so he can overturn any of them with
+`/k0-discuss`; the assignments left out and what they needed; whatever the repairs did not fix; and
+that the stories are sitting in `Review` waiting for him to press `Done`, which is his and nobody
+else's.

package/.claude/skills/k0-ultracode/references/agent-brief.md

@@ -0,0 +1,71 @@
+# What an agent is told, and what it owes back
+
+One agent, one assignment, one worktree. The brief is written by the manager and sent with the
+`Agent` tool; the agent type is `general-purpose` and the model is the one the session is already
+running. Nothing below is optional: a brief missing the decisions is a brief that produces work
+somebody has to throw away.
+
+## The brief
+
+```
+You are one of several agents working on <KEY> — <story title>.
+
+Your assignment
+  <what this assignment finishes, in two or three lines, from the plan step it came from>
+
+Write only here
+  <the worktree path>
+  Every path you touch is absolute and under it. Nothing is written in the base repository —
+  not a file, not a note, not a scratch script. The repository has no .env and no node_modules
+  on purpose.
+
+The files that are yours
+  <the files this assignment owns>
+  Another agent owns the rest right now. Needing a file that is not on this list is a question,
+  not a decision: report it and stop touching it.
+
+The constraints — already decided
+  D2 — <the decision, verbatim>
+  K7·D3 — <the decision, verbatim>
+  These are not advice. Work that contradicts one of them is wrong work, however well written.
+  If the assignment cannot be done without breaking one, stop and report it.
+
+Never
+  no tests, no build, no dev server, no npm run of any kind;
+  no git commit, no git merge, no branch, no push, no pull request;
+  no call to the k0 API and nothing written to .k0/;
+  no work outside your worktree.
+
+When you are done, your final message is the report below and nothing else — no preamble, no
+summary for a human. It is read by a program.
+```
+
+## The report
+
+The last message is JSON and nothing else:
+
+```json
+{
+  "done": "what is now true that was not true before, in two or three lines",
+  "files": ["path/one.js", "path/two.js"],
+  "assumptions": ["a choice taken because nothing decided it, one per line"],
+  "questions": ["a question only the user can answer, one per line"],
+  "blocked": null
+}
+```
+
+- `done` is written for whoever reads the Log, not for the user: names of files are welcome.
+- `assumptions` is the list the manager turns into Log entries and, at the end, into the things the
+  user is told he can overturn. An agent that took no choices returns an empty list — never a
+  reassuring sentence.
+- `questions` is what the agent could not settle by itself. Where it went ahead anyway it says so
+  in `assumptions` as well, so the manager knows which questions have code behind them already.
+- `blocked` is a sentence when the assignment could not be finished, and `null` when it could. An
+  agent that half-finished says so here rather than in `done`.
+
+## What the manager does with it
+
+The report is not committed and not shown raw to the user. It becomes: a Log entry, an assumption
+list, the questions of §7, and — when `blocked` is set — one of the repair attempts of §8. An agent
+is never asked to try again on the spot: the budget is counted in one place, and that place is the
+manager.

package/.claude/skills/k0-ultracode/references/modes.md

@@ -0,0 +1,49 @@
+# How much rope, and how hard
+
+Two questions, asked once, in §3 of `/k0-ultracode`. One `AskUserQuestion` with both of them in it,
+and no `preview` on any option — a single-choice question with a preview loses the free-text box,
+and this is the moment the user is most likely to want to type something of his own.
+
+## How much rope
+
+**`interactive`** — everything passes the user. Each assignment is shown as it lands, each question
+an agent brings back is asked while it is still warm, each conflict is his to settle. The slowest,
+and the one to offer when the work touches something he cares about.
+
+**`checkpoint`** — three stops and no others: the cut into assignments before any agent starts,
+the moment before the story goes into the branch, and a red test run. Questions from agents are
+held and asked in a batch at the next stop.
+
+**`autonomous`** — no stops. Assumptions are taken and written down, and the run comes back when
+the epic is finished. It stops early for three things and nothing else:
+
+- an answer that would contradict a decision that is still standing;
+- a conflict that cannot be resolved inside the files one assignment owned;
+- the tests still red after the last repair attempt.
+
+Autonomous means autonomous. A mode that asks anyway is the mode the user did not choose, and the
+question that could have waited for the final block should have waited for it.
+
+## How hard
+
+| | agents at once | repair attempts | the fresh pair of eyes |
+|---|---|---|---|
+| `light` | 2 | 1 | one agent |
+| `medium` (default) | 3 | 2 | one agent |
+| `hard` | 5 | 2 | two agents, a lens each — the decisions, correctness — and a third asking what the plan forgot |
+
+The numbers are ceilings, not targets: three slots do not mean three assignments, and a plan that
+cuts into two is done by two. A fourth agent waits for a slot rather than starting.
+
+Nothing here loops until it runs out of things to find. The repair attempts are spent and then the
+run says what is still broken — that is the difference between this and a run that never ends.
+
+## Saying it back
+
+One line to the user, and the same line into the Log, before anything starts:
+
+> autonomous, medium: three agents at a time, two repair attempts, and I come back when the epic is
+> done or when something is genuinely stuck.
+
+A run picked up cold reads that line first and keeps the contract the user agreed to, rather than
+choosing a new one on his behalf.

package/.claude/skills/k0-verify/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: k0-verify
+description: The counter-check on a story whose work is finished — it takes every decision that was made about that story one at a time, not as a group, and records kept, violated or not applicable with the evidence, the file and the line or a sentence saying why it does not apply. Then it runs the checklist, doing itself everything a machine can do (the project's tests, and the browser through Chrome DevTools when the thing is a web application) and leaving the user only what genuinely needs a person. Use this skill when the user types "/k0-verify" or says "check it against what we decided", "verify this story", "did it do what we agreed", "controlla se ha rispettato le decisioni", "verifica la storia", "fai il controllo finale". Do not use it to review code in general, to run the tests on their own, or to mark a story Done: it proposes closing, it never closes.
+---
+
+# /k0-verify [story key]
+
+A discussion is only worth what somebody later checks. This is the check. One decision, one
+verdict, one piece of evidence — and no summary standing in for the row.
+
+## Before anything
+
+```bash
+PORT="${K0_PORT:-4319}"
+REPO="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)"; REPO="${REPO%/.git}"
+[ -d "$REPO" ] || REPO="$(git rev-parse --show-toplevel 2>/dev/null)"
+curl -sS --max-time 30 --get --data-urlencode "repo=$REPO" \
+  "http://127.0.0.1:$PORT/api/backlog" -o "$SCRATCH/k0-board.json"
+```
+
+`127.0.0.1`, not `k0.localhost`: browsers resolve that name by themselves, `curl` does not.
+`--get --data-urlencode`, not `?repo=$REPO`: a repository path with a space in it makes `curl`
+refuse the address outright, and one with a `#` in it quietly sends half.
+`$SCRATCH` is the session's scratch directory; nothing is written outside it. `REPO` is the
+repository the stories are filed under — the main one, even when this session sits in a
+subdirectory of it or inside a session's worktree. That last case is the reason it is not `$PWD`:
+`/k0-verify` is typed exactly where `/k0-work` has just been working.
+
+- `curl` cannot connect → the k0 server is not running. Say so (`k0-board start`, or the tray
+  icon → *Restart*) and **stop**.
+- `{"enabled": false}` → say in one line that the backlog is switched off in k0's settings and
+  **stop**.
+- `REPO` empty, or an answer with no `stories` in it at all → this is not a checkout, and the
+  server said so rather than answering with a board. Say that, ask once which repository the
+  story is in, and take the path he gives. It is not an empty backlog: reporting it as one sends
+  him looking for stories that were never missing.
+- **A listing with `stories: []`** → say that plainly and stop. There is nothing here to check
+  against, and it is not a reason to ask the user for what the board would have told you.
+
+That answer holds every story in this repository with its key, state and title, so work
+out which story is meant from it — never ask the user for a key you can look up. With no
+argument, take the story of the session you are in, or the one in `Working`; if two could be
+meant, ask once, showing both.
+
+Then fetch the story and read all of it — rounds, decisions, checks, plan, log:
+
+```bash
+curl -sS --max-time 30 "http://127.0.0.1:$PORT/api/backlog/story/$STORY_ID" -o "$SCRATCH/k0-story.json"
+curl -sS --max-time 30 -X PATCH "http://127.0.0.1:$PORT/api/backlog/story/$STORY_ID" \
+  -H 'content-type: application/json' -d '{"state": "Review"}'
+```
+
+A run of checks is what puts a story in `Review`.
+
+**The run number comes out of that file, not out of your head.** It carries `latest_run`, and the
+run you are about to write is **`latest_run + 1`** — `0` there means nothing has ever been checked
+and this is run 1. `runs` beside it lists what each earlier run found. Do not count anything
+yourself: a run that collides with an earlier one quietly rewrites what was checked last time.
+
+**Put the whole run on tasks before looking at anything.** One task per standing decision, its
+subject the label and a few words of the sentence; then one per checklist item — or a single
+*write the checklist* when there is none — and a last one for the outcome. A decision's task goes
+`in_progress` when you start looking and `completed` when its verdict is written down, with the
+verdict and the evidence in its description. Nothing is marked completed on the strength of a
+group: the tasks exist so that a skipped decision shows up as a task still open. If `TaskCreate`
+is not among your tools, say so in one line and carry on; never call it again to see whether it
+has come back.
+
+## 1. Every decision, one at a time
+
+Walk the decisions in the order the file has them. **Never in a group, never as a summary, never
+"the rest were all respected".** A decision skipped is the whole failure this feature exists
+to prevent.
+
+Each one carries a `label` and an `owner`, and both matter:
+
+- `owner: "story"` — labelled `D3`. Decided about this story.
+- `owner: "epic"` — labelled `K7·D3`. Decided about the whole epic, before this story existed,
+  and inherited by every story under it. It is checked here exactly like the story's own, and the
+  verdict is about **this** story: the same epic decision can be kept in one story and violated in
+  another, and that is right, not a contradiction to resolve.
+
+Use the label when you talk about a decision, always. `D3` and `K7·D3` are two different
+sentences and a story usually has both.
+
+For each one, go and look. Read the code, the interface, the file it says will exist — do not
+answer from what you remember writing.
+
+| verdict | when | evidence |
+|---|---|---|
+| `kept` | the finished work does what the sentence says | `server/db.js:120` — the file and the line where it is true |
+| `violated` | it does not, or it does something else | the file and line where it goes wrong, and one sentence saying how |
+| `na` | the sentence cannot apply to this work | one sentence saying why, in the user's language |
+
+`na` is for a decision about something that was never built in this story, and for one that was
+**superseded**: the evidence is *superseded by* the label of whatever replaced it, and that one is
+what gets checked.
+
+`na` is not an escape hatch. If you cannot find where a decision landed, that is `violated`,
+not `na` — "I could not find it" is a finding, not an exemption.
+
+Post the whole run in one call, all decisions together, once you have looked at all of them:
+
+```bash
+curl -sS --max-time 30 -X POST "http://127.0.0.1:$PORT/api/backlog/story/$STORY_ID/verify" \
+  -H 'content-type: application/json' -d @"$SCRATCH/k0-verify.json"
+```
+
+with `{ "run": 2, "results": [{ "decision_id": 41, "verdict": "kept", "evidence": "…" }, …] }`.
+**Name each decision by its `id`**, the row id from the file — not by its number. A story's `D3`
+and its epic's `K7·D3` are both "3", and a number would attach half the run to the wrong
+sentences. Write the JSON to a file and send it with `-d @file`: evidence sentences carry quotes
+and newlines and do not survive being pasted inline.
+
+**A run is the whole set.** The server answers `409` and writes nothing if a decision that is
+still standing has no verdict in it, and names the ones it did not find — look at those and send
+the whole run again. Nothing is half-recorded, so there is no half-run to repair.
+
+## 2. The checklist
+
+The checklist is what somebody would do to convince themselves the story is finished. If the
+story has one, use the items already in `$SCRATCH/k0-story.json` — each carries the `id` you will
+mark it with.
+
+If it has none, write one — one line per thing, plain language — post it, and then **fetch the
+story again**, because posting replaces the whole checklist and the items you are about to mark
+are new rows with ids that did not exist a moment ago:
+
+```bash
+curl -sS --max-time 30 -X POST "http://127.0.0.1:$PORT/api/backlog/story/$STORY_ID/check" \
+  -H 'content-type: application/json' -d @"$SCRATCH/k0-checks.json"     # { "items": [{ "text": "…" }] }
+
+curl -sS --max-time 30 "http://127.0.0.1:$PORT/api/backlog/story/$STORY_ID" -o "$SCRATCH/k0-story.json"
+```
+
+Never `PATCH` a check by an id you have not just read back. A stale id either fails or marks the
+wrong line passed, and a checklist that says something was proved when it was not is worse than
+no checklist.
+
+**Do yourself everything a machine can do.** The user's time is the scarce thing here; leaving
+him a checklist you could have run is handing back your own work.
+
+- **The project's tests** — run them the way the repository runs them, on the branch that holds
+  the merged work, never inside a session worktree: the worktree's copied `.env` carries the
+  base repository's port, and a runner that reuses a live server goes green against the wrong
+  code.
+- **The browser, through Chrome DevTools MCP**, when the thing has an interface: open the page,
+  do the gesture the decision describes, look at it. A screenshot is evidence; "it should work"
+  is not.
+- **Anything else with an exit code** — a build, a linter, a script the repository already has.
+
+Record each one as you go, so a terminal that dies keeps what was already proved:
+
+```bash
+curl -sS --max-time 30 -X PATCH "http://127.0.0.1:$PORT/api/backlog/check/$CHECK_ID" \
+  -H 'content-type: application/json' -d '{"state": "pass", "evidence": "npm test — 214/214", "by": "claude"}'
+```
+
+`$CHECK_ID` is the `id` of that item as it came back from the story. `state` is `pass`, `fail` or
+`skip`; `by` is `claude` for what you ran.
+
+**What is left for the user** is only what genuinely needs a person: a judgement about how
+something feels, a device or an account you do not have, an action with a consequence outside
+this machine. Leave those `todo`, list them as a short numbered list with what to look at and
+what would count as passing, and mark them `pass` or `fail` with `"by": "user"` from what he
+answers. Never mark them yourself.
+
+## 3. The outcome
+
+Present it in the user's language, in this order and nothing more:
+
+1. one line: how many decisions, how many kept, how many violated, how many not applicable;
+2. **every `violated` decision in full** — the sentence, quoted, and where it went wrong;
+3. **the kept ones, one line each** — the number and the sentence, short. Not a count standing in
+   for them: those sentences are the reason he sat through the discussion, and *"the other nine
+   were fine"* is exactly the summary this skill exists to refuse. Say where the full record with
+   the evidence lives, in one line: the story's page on the board, and the *Verification* section
+   of `<repo>/.k0/stories/K42-….md`, which is a plain file he can open six months from now;
+4. the checks that failed;
+5. the checks still waiting on him.
+
+Then, and only then, the proposal. **You never close anything.** `Done` is the button on the
+board, pressed by the user, and nothing else may set it.
+
+- Everything kept, every check passed → say the story looks finished and that pressing **Done**
+  on the post-it is what closes it.
+- **A `violated` verdict standing unacknowledged → do not propose closing at all.** Not softly,
+  not with a caveat. Say what is broken and offer to fix it, or wait for him to say the verdict
+  is wrong or that he accepts it — an acknowledged violation is one he has answered, and his
+  answer becomes a decision of its own through `/k0-discuss`. Write it the way
+  `../k0-discuss/references/rounds.md` says decisions are written — the path is relative to the
+  folder this skill was loaded from, and the two skills are siblings wherever k0 is installed —
+  and then verify again as a new run.
+- Checks still waiting on him → say what you need from him and stop there.
+
+Last, append what happened to the story's log:
+
+```bash
+curl -sS --max-time 30 -X POST "http://127.0.0.1:$PORT/api/backlog/story/$STORY_ID/log" \
+  -H 'content-type: application/json' -d @"$SCRATCH/k0-log.json"        # { "text": "…", "session_id": "…" }
+```
+
+## Rules
+
+- **Talk to the user in his language, and store what he says in his language.** The evidence
+  strings that are file and line stay as they are; the sentences around them are his.
+- **Never ask for what the API can tell you** — the key, the state, the decisions,
+  what is blocked. It is all in the two calls at the top.
+- **Do not invent evidence.** A line number you did not open is worse than no verdict.
+- **Do not edit or delete a decision.** Verdicts are recorded against it; the sentence itself
+  only ever changes by being superseded, and that is `/k0-discuss`'s job.
+- **No files outside the scratch directory.**
+- A second run never overwrites the first. Runs stack, and reading them in order is how
+  somebody sees that the thing was actually fixed — which is why the run number is read off the
+  story rather than assumed.
+- **A violation is never cleared by silence, and never by `na`.** It stands until a later run
+  finds that decision `kept`, or until the decision itself is superseded because it was the
+  decision that was wrong. Those are the two answers, and the board holds you to them: a story
+  cannot be marked Done while one is open, whatever any later run says about anything else.