k0-board 0.4.0 → 0.5.0

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

@@ -27,7 +27,7 @@ whole thing. Markdown, starting at the first word that belongs to the summary.
       "unpushed_total": 2,
       "uncommitted_files": ["web/board.js"],
       "unreleased_changelog": ["### Fixed", "- the board stays pinned to the bar"],
-      "cards": [{ "title": "…", "description": "…", "status": "IDLE", "done": false }]
+      "stories": [{ "title": "…", "description": "…", "status": "IDLE", "done": false }]
     }
   ]
 }
@@ -73,7 +73,7 @@ something to put in them. This is a summary somebody reads standing up.
 
 ## Rules
 
-- **Write in the language of the facts.** The commit subjects and the card titles tell you what
+- **Write in the language of the facts.** The commit subjects and the story titles tell you what
   language this person works in: write in that one, and do not translate anything. The headings,
   the bold lines, the bullets — all of it in their language.
 - **Leave the words of the trade alone.** *commit*, *push*, *branch*, *changelog* are what these

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

@@ -0,0 +1,105 @@
+---
+name: k0-discuss
+description: Takes a story that is already on the k0 board and still too vague to build, and discusses it in rounds of questions until the decisions behind it are written down one by one. Appends to the rounds and decisions the story already has instead of starting the conversation again. Use this skill when the user types "/k0-discuss", or says "discuss K42", "this story is too vague", "let's talk it through before I start", "pick up the discussion on K19", "parliamo di K42", "questa storia è troppo vaga", "riprendiamo la discussione su K19", "discutiamo prima di partire". Do not use it to create a story from nothing (that is /k0-story or /k0-epic), to break up a story that will not close (/k0-split), or to plan one whose decisions are already recorded (/k0-plan).
+---
+
+# /k0-discuss [key]
+
+A story on the board says what it is called and not much else. This turns it into something
+buildable: rounds of questions, and a row of decisions somebody can hold the finished work up
+against six months from now.
+
+`[key]` is `K42`, or nothing — with nothing, work out which story from what the user just said.
+
+## The rules of a round live in one file
+
+Read `references/rounds.md` — it sits in this skill's own folder — and follow it. How many rounds
+and how to say it, when to stop, the fifteen-round ceiling, how to ask, what to do when two
+answers collide, how to write a decision, and why every round is written to the API before the
+next question is asked: all of that is there and none of it is repeated here.
+
+**If you cannot read that file, say so and stop.** Those rules are the method. Running the
+discussion without them produces exactly the pleasant, unchecked conversation the whole feature
+exists to prevent.
+
+What follows is only what is particular to discussing a story that already exists.
+
+## Procedure
+
+1. **Find the story, and check the feature is on.**
+
+   ```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; 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 worktree, which is why it is not `$PWD`.
+
+   - `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**. Do not run the discussion anyway and do not offer to turn it on.
+   - `REPO` empty → this is not a git repository. Ask once which repository this belongs to and
+     take the path he gives.
+
+   The listing carries every key, title and state. Match the key the user gave, or the
+   title he described. If two stories match, ask which one; never pick one and hope. If the
+   listing has no stories at all, say so — an empty board is not the same as a story you failed
+   to find, and it usually means the work has never been written down here.
+
+2. **Read everything already recorded.**
+
+   ```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 you matched in step 1, not the key. Rounds, decisions,
+   plan, checks, log. This is the whole point of the skill: a second discussion that ignores the
+   first one is worse than no second discussion, because it spends the user's evening asking him
+   things he has already answered.
+
+3. **Say where you are picking up from**, in one line, before the first question:
+
+   > K42 already has four rounds and six decisions from 3 September. Round 5 of about 7.
+
+   On a story with no rounds yet, say that instead and start at round 1.
+
+4. **Run the rounds** exactly as `references/rounds.md` describes. Every round POSTed before the
+   next question leaves your mouth, every decision POSTed the moment it is settled.
+
+5. **Close the account.** The new decisions, by number, in his words — a short list, not a
+   retelling of the conversation. Then, unless the story is already `Planned`, `Working`,
+   `Review` or `Done`, move it on:
+
+   ```bash
+   curl -sS -X PATCH "http://127.0.0.1:$PORT/api/backlog/story/$STORY_ID" \
+     -H 'content-type: application/json' -d '{"state": "Discussed"}'
+   ```
+
+   Then one line saying what comes next — `/k0-plan K42` — and stop there. Do not start planning.
+
+## Rules
+
+- **Append, never replace.** New decisions get new numbers. One that contradicts an older one
+  goes through the collision rule in §4 of `references/rounds.md`: the old sentence is marked
+  superseded by the new one's `id`, never edited and never deleted. Nothing in this skill sends
+  a `DELETE`.
+- **The body is his, not yours.** If the discussion changes what the story is fundamentally
+  about, `PATCH` the `body` — but with his sentences, in his language, and say that you did.
+- **A story mid-flight is still discussable.** `Working` or `Review` is not a reason to refuse.
+  It is a reason to read the log first, and to say out loud that work has already started, so
+  that a new decision contradicting what is built is recognised as the rework it is.
+- **Talk in the language the user speaks, and store what he says in that language.** The story
+  carries a `lang`: if it is empty, set it from the language of the discussion.
+- **Never ask what the API can tell you** — the key, the epic, the dependencies, what
+  is open, how far the epic has got. It is in the two calls above. See §7 of `references/rounds.md`.
+- **No files outside the scratch directory**, and never write into `.k0/` by hand: the server
+  mirrors the story there on its own.

package/.claude/skills/k0-discuss/references/rounds.md

@@ -0,0 +1,280 @@
+# The rounds engine
+
+This is the one place the rules for discussing a story live. `k0-discuss` runs on them, and
+`k0-epic`, `k0-split`, `k0-plan`, `k0-work` and `k0-verify` read this file instead of restating
+it — they reach it as `../k0-discuss/references/rounds.md`, relative to the folder the skill
+itself was loaded from, which is where it is whether k0 runs installed from npm or from a
+checkout. If you find these rules written out somewhere else, that copy is wrong and this one
+wins.
+
+## Why any of this exists
+
+The person you are talking to has already been through a long, pleasant discussion with a
+model that asked good questions, understood the answers, agreed with everything — and then
+built something that quietly contradicted half of it. Nothing checked. Nothing compared the
+finished work against what had been decided, because nothing had written down what had been
+decided in a form anybody could check.
+
+So the discussion was worthless. Worse than worthless: it cost an hour and bought a false
+sense that the thing was understood.
+
+Everything below exists to stop that happening again. The questions are not the point. The
+point is the row of decisions the questions leave behind, each one a sentence a person can
+read six months later and hold the work up against. `/k0-verify` will do exactly that, one
+decision at a time. Write them so it can.
+
+---
+
+## 1. How many rounds, and saying it out loud
+
+Before the first question, list the **open unknowns**: the things where a different answer
+would produce different work. Not the things you are curious about — the things that fork the
+build. A question whose two answers lead to the same code is not an unknown.
+
+Then:
+
+- rounds still needed ≈ open unknowns ÷ 3, rounded up (three, not four: the fourth slot is
+  for what an answer opens up);
+- estimated total = rounds already run + that;
+- say it in the first line of every round: **"Round 3 of about 8"**, in the user's language.
+
+The word *about* is doing real work. It is an estimate and it is allowed to move.
+
+**Recount after every answer**, because answers both close unknowns and create them. When the
+number moves, say so in the same breath — one short clause, no apology:
+
+> Round 4 of about 6 — two of the questions answered themselves.
+
+> Round 5 of about 9 — invoicing turned out to have its own states.
+
+**Never let the number drift in silence.** Announcing 8 and then quietly asking a twelfth
+question is the thing that makes people stop trusting the count. If you cannot say why the
+number moved, the number did not move: you miscounted, and you say that instead.
+
+If the estimate ever climbs past about twelve, stop and say what you are seeing: a story that
+needs twelve rounds is usually two stories. Offer `/k0-split`. The user decides.
+
+Every round is written to the API with the estimate it was asked under, so the record shows
+what you believed at the time — see §6.
+
+## 2. When to stop
+
+Stop when **no remaining question would change what gets built.** That is the whole test, and
+it is stricter than it sounds. Apply it to each unknown still on your list:
+
+- *Would a different answer change the work?* No → drop it, do not ask it.
+- *Can it be decided during the work, and cheaply undone if it is wrong?* Then it is not a
+  decision for now. Decide it yourself later, and say so in one line.
+- *Is it a preference the user will notice the moment he sees it?* Ask.
+
+Do not run a last round to be thorough. Thoroughness here means one more question the user has
+to answer to get where he was already going.
+
+**The ceiling is 15 rounds.** At 15 you stop, whatever state the discussion is in. Post the
+last round, then show what is still open — a plain list of the unknowns you never got to,
+in the user's words — and say the story is recorded as it stands and can be picked up again
+whenever he wants. Do not ask a sixteenth question. Do not decide the open ones yourself to
+make the list look finished. A discussion that hits 15 is telling you the story is too big;
+say that too, and offer to split it.
+
+## 3. How to ask
+
+`AskUserQuestion`, **at most four questions per round**. Four is a ceiling, not a target: two
+sharp questions beat four vague ones, and a round of one is fine.
+
+**Never pass `preview` on an option.** With `preview` set on a single-select question the
+interface switches to a side-by-side layout and the free-text box — *Type something.* —
+disappears. That box is how this user actually answers. He picks one of your options perhaps
+half the time; the rest of the time he types the answer you did not think of, and that answer
+is usually the good one. Taking the box away to show a nicer layout is a bad trade every
+single time. There is no exception.
+
+For each question:
+
+- **One unknown per question.** Two unknowns bundled into one question get one answer, and you
+  will not know which one it settled.
+- **Two to four options**, and put the **one you recommend first**. You have read the story;
+  having no opinion is not neutrality, it is work handed back.
+- **The description carries the trade-off**, never a restatement of the label. It says what you
+  give up by choosing this. If you cannot name what is lost, you have not understood the
+  choice well enough to ask about it.
+- Short labels. The description is where the sentence goes.
+
+Good:
+
+> **The user presses Done** — nothing closes a story by itself. Safest, but a finished story
+> can sit on the board for days looking unfinished.
+>
+> **The last check passing closes it** — no housekeeping, but a story can close while you are
+> still looking at it.
+
+Bad — the description says the label again:
+
+> **The user presses Done** — the user has to press Done to finish the story.
+
+Then **listen to the free text.** When the typed answer does not match any option, the typed
+answer is the answer. Do not re-ask in the hope of getting a clean click.
+
+## 4. When two answers collide
+
+**Before every round**, fetch what has already been recorded and read it — do not trust your
+memory of the conversation:
+
+```bash
+curl -sS --max-time 30 "http://127.0.0.1:$PORT/api/backlog/story/$STORY_ID" -o "$SCRATCH/k0-story.json"
+```
+
+Its `decisions` array is everything that binds this story: the decisions taken on it, and the
+ones taken on its epic before it existed, which it inherits. Each carries an `owner` — `story` or
+`epic` — and a `label`, `D3` or `K7·D3`. There is nowhere else to look: an epic's decisions are
+rows on the epic, never prose in its `body`, and `body` is only the Why.
+
+The inherited ones are the ones a later answer most often contradicts, because they were settled
+weeks ago about the whole area and nobody in this conversation has said them out loud.
+
+Compare the answer that just arrived against every decision in that list. A collision is when
+the two **cannot both be true of the finished work**. A later answer that adds detail to an
+earlier one is not a collision; do not cry conflict over a refinement, it teaches the user to
+ignore you when it matters.
+
+When they do collide, **stop in the middle of the round.** No next question, no smoothing it
+over, no picking the newer one because it is newer.
+
+Put both in front of him, quoted, by number:
+
+> These two do not fit together.
+>
+> **D3** — A story can go straight from Backlog to Done, and nothing warns about it.
+> **just now** — Nothing may leave Review until every check has passed.
+>
+> I think **D3** should win: you asked for no mandatory path twice, and the check rule only
+> bites on stories that got as far as Review. But it is your call.
+
+Say which one you think should win **and why**, in one sentence, and then wait. Do not continue
+the discussion until he has chosen.
+
+On the record, **the last answer wins**: the choice becomes a new decision with its own number,
+and the loser is marked superseded — never edited, never deleted.
+
+```bash
+curl -sS -X POST "http://127.0.0.1:$PORT/api/backlog/story/$STORY_ID/decision" \
+  -H 'content-type: application/json' -d @"$SCRATCH/k0-decision.json" \
+  -o "$SCRATCH/k0-new-decision.json"                                  # → { "id": 148, "n": 9, … }
+
+curl -sS -X PATCH "http://127.0.0.1:$PORT/api/backlog/decision/$OLD_ID" \
+  -H 'content-type: application/json' -d '{"superseded_by": 148}'
+```
+
+**`superseded_by` takes the new decision's `id`, never its `n`.** They are different numbers and
+they look alike: `id` is the row's own, unique across the whole database, and it is what the
+answer to the POST carries next to `n`; `n` starts again at 1 on every story, so sending it
+points the supersession at some other story's decision, or at nothing. Read the `id` out of the
+answer. Never type a number you worked out yourself, and never reuse the one in the example.
+
+**Supersede a decision where it lives, not where it is read.** An epic's decision is superseded on
+the epic — one call, and every story under it sees the change at once. That is the whole reason it
+belongs to the epic. The only copies that ever need chasing are the ones `/k0-split` made when it
+cut a story into tasks, and those are the story's own, not the epic's: if this story has tasks
+under it that carry a copy of the decision you are reversing, supersede each of those too, with
+that task's own decision `id`. A copy left standing is a rule `/k0-verify` will go on holding the
+finished work up against long after the user reversed it.
+
+The old sentence stays readable with *(superseded by D9)* beside it. That is not bookkeeping:
+six months on, knowing a decision was made and then reversed is worth more than a tidy list
+that pretends it never happened.
+
+## 5. How to write a decision
+
+This is the part the whole feature stands on. A decision is what `/k0-verify` will hold the
+finished work up against, one at a time. A decision nobody can check is a decision that was
+not made.
+
+- **One complete sentence.** Subject, verb, the thing that will be true. Not a fragment, not a
+  heading, not a note to self.
+- **Behaviour, not implementation.** What the user will see, do, or be spared. No file paths,
+  no table names, no function names, no jargon. He does not read code and should not have to.
+- **One decision per line.** Never merge two, however neatly they pair.
+- **Never lose one.** Half-swallowed by voice dictation, said badly, said twice in different
+  words, dropped into the middle of an answer about something else — it still counts. When a
+  sentence came out garbled, read back what you think he meant and ask; do not quietly bin it
+  and do not guess.
+- **In the language he spoke.** The decisions are for him, not for the repository.
+- Write it the moment it is settled, in the same breath as the round it came from (§6).
+
+### Three that work
+
+- Nothing marks a story finished on its own: the user presses Done.
+- A story can go straight from Backlog to Done, and nothing warns about it.
+- Every post-it shows the name of the epic it belongs to, in that epic's colour.
+
+Each one is a sentence, describes something visible, and can be checked by looking at k0.
+
+### Three that do not
+
+- *Add `epic_id` to the story table and join it in `listStories()`.*
+  Implementation, and the two things he would need in order to check it — a table and a
+  function — are things he never looks at. Rewritten: *a story remembers which epic it belongs
+  to, and keeps it when it is moved.*
+
+- *Colours and states.*
+  Not a sentence and not a decision. In six months nobody, including you, can say what was
+  agreed. If this is all you have, you did not get an answer: ask again.
+
+- *Use the epic's colour on the post-it, and allow Backlog → Done directly, and keep Done
+  manual.*
+  Three decisions on one line. When one of them is reversed there is no way to strike only
+  that one, so the whole line goes stale and the other two rot with it.
+
+## 6. Write it down before you ask the next thing
+
+**Every round is POSTed before the following question leaves your mouth.** Not batched at the
+end, not held in the conversation and written up when the discussion closes.
+
+```bash
+curl -sS -X POST "http://127.0.0.1:$PORT/api/backlog/story/$STORY_ID/round" \
+  -H 'content-type: application/json' -d @"$SCRATCH/k0-round.json"
+```
+
+with `{ "n": 3, "estimated_total": 8, "question": "…", "answer": "…" }` — `n` is 1-based per
+story, `estimated_total` is what you announced for *that* round. Decisions go the same way, the
+instant they are settled, not when the discussion ends.
+
+The reason is plain: terminals die. A crash at round three must not take the first three with
+it, and it must not leave the user re-answering questions he has already answered — that is
+exactly the moment people stop using a tool. Write the JSON to a file under `$SCRATCH` and send
+it with `-d @file`; long answers with quotes and newlines in them do not survive being pasted
+inline.
+
+Resuming is then automatic: fetch `GET /api/backlog/story/:id`, read the rounds and decisions
+already there, carry on at the highest `n` + 1, and say where you are picking up from. Never
+start again at round 1 on a story that already has rounds.
+
+If `curl` cannot connect, the k0 server is not running. Say so (`k0-board start`, or the tray
+icon → *Restart*) and **stop**. Do not run the discussion anyway and promise to save it later:
+that promise is the failure this file exists to prevent.
+
+## 7. What you never ask
+
+His time is the scarce thing here. Two kinds of question waste it.
+
+**What the server already knows.** Fetch it; do not ask, and do not reason it out either.
+
+| you want | where it comes from |
+|---|---|
+| the key, the title, the state | `GET /api/backlog?repo=<path>` |
+| which epic, how far along it is | the same call — `progress: {done, total}` |
+| what was decided while the epic was discussed | `GET /api/backlog/story/:id` — already merged into `decisions`, marked `owner: "epic"` |
+| what is open, what is blocked, the dependencies | the same call — `state`, `blocked`, `deps` |
+| the rounds, decisions, checks, plan and log so far | `GET /api/backlog/story/:id` |
+| what to pick up next, and why | `GET /api/backlog/next?repo=<path>` |
+
+Counting is not what a model is for. Understanding what he means and writing it down clearly
+is. Asking him for a number the database is already holding makes him do the machine's job.
+
+**Anything with an obvious default.** Decide it, and say what you decided in one line he can
+push back on — *"I am taking the story's colour from its epic unless you say otherwise"* — and
+carry on without waiting. A round spent confirming the obvious buys nothing and spends the
+attention you will need for the question that actually matters.
+
+Also never ask: something he has already answered in this session; the same unknown a second
+time in different words; permission to continue; or a question whose answer you would ignore.

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

@@ -0,0 +1,196 @@
+---
+name: k0-epic
+description: The long way in. The user talks for ten minutes about something big — a feature, a rewrite, a whole area of the product — and this turns it into an epic on the k0 board: rounds of questions until nothing is left that would change the work, a decision written down for each thing settled, and only then a tree of stories proposed for approval and created. Use this skill when the user says "/k0-epic", "new epic", "let me tell you about something big", "I want to think this through with you", "break this down for me", or in Italian "nuovo epic", "ti racconto una cosa grossa", "ragioniamo su questa feature", "spacchettiamo questo lavoro". Do not use it for one thing he already knows he wants — that is /k0-story — nor to discuss, split or plan a story that already exists: those are /k0-discuss, /k0-split and /k0-plan.
+---
+
+# /k0-epic
+
+Somebody is about to describe something too big to be one post-it. The work here is in this
+order and no other: **understand, record, propose, then write.** Thirty stories created before
+he has agreed to them is thirty things he now has to delete.
+
+## 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-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; 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 worktree, which is why it is not `$PWD`.
+
+- `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 → this is not a git repository. Ask once which repository this belongs to and
+  take the path he gives.
+
+That one answer also holds the repository's existing epics and stories. Read it before you open
+your mouth: half of what he is about to describe may already be on the board, and saying so is
+worth more than a good question.
+
+## 1. Let him finish
+
+He is dictating, probably out loud, probably jumping about. Do not interrupt with round one
+while he is still going. When he stops, say back in three or four lines what you understood the
+thing to be — not a summary of his words, the shape of the work — and let him correct it.
+
+## 2. Create the epic straight away
+
+As soon as there is a title and a why, before the first question:
+
+```bash
+curl -sS --max-time 30 -X POST "http://127.0.0.1:$PORT/api/backlog/epic" \
+  -H 'content-type: application/json' -d @"$SCRATCH/k0-epic.json" -o "$SCRATCH/k0-epic-new.json"
+```
+
+with `{ "project_path": "…", "title": "…", "body": "…", "lang": "it" }`. The `body` is why this
+epic exists, in his words and his language. The answer carries the `key` and the
+`id`; use those from now on and never work them out yourself.
+
+An epic with no stories yet costs nothing and means the next ten minutes survive a dead terminal.
+
+## 3. Run the rounds
+
+The rules for this are in one place and this skill does not repeat them:
+
+**`../k0-discuss/references/rounds.md` — read it now and follow it.** The path is relative to
+the folder this skill was loaded from; the two skills are siblings wherever k0 is installed. If
+you cannot find the file, say so and **stop** — those rules are the method, and an epic
+discussed without them is the long pleasant conversation nobody ever checks.
+
+How many rounds and how to announce them, when to stop, the ceiling, how to ask, what to do when
+two answers collide, how to write a decision, and what never to ask: all of it is there and all
+of it applies here unchanged.
+
+One thing is particular to an epic: the rounds and the decisions belong to the **epic itself**,
+not to a story, and not to its body.
+
+**Write every round on the epic, before the next question.** An epic has rows of its own for
+exactly this — there is no need to keep the transcript anywhere, and no reason to.
+
+```bash
+curl -sS --max-time 30 -X POST "http://127.0.0.1:$PORT/api/backlog/epic/$EPIC_ID/round" \
+  -H 'content-type: application/json' -d @"$SCRATCH/round.json"
+```
+
+`{ "n": 3, "estimated_total": 8, "question": "…", "answer": "…" }`, in his language. Writing the
+same `n` twice replaces that round, so the question can go down when you ask it and the answer
+when it arrives — that is one round, not two.
+
+**Write every decision on the epic as it is taken.**
+
+```bash
+curl -sS --max-time 30 -X POST "http://127.0.0.1:$PORT/api/backlog/epic/$EPIC_ID/decision" \
+  -H 'content-type: application/json' -d '{"text":"…","source":"discussion"}'
+```
+
+It comes back with `id` and `n`. Keep the `id`: superseding takes a row id and never a number.
+
+**`body` is the Why and nothing else.** Never grow it into a transcript. A decision written into
+prose cannot be counter-checked one at a time, which is the one thing this whole feature is for,
+and it cannot be superseded either — the strikethrough is a mark on a paragraph, not a change to
+anything `/k0-verify` reads.
+
+**The collision check reads the epic's decisions.** §4 of `rounds.md` says to fetch what is
+already recorded before every round rather than trusting your memory of the conversation. Here
+that is the epic:
+
+```bash
+curl -sS --max-time 30 "http://127.0.0.1:$PORT/api/backlog/epic/$EPIC_ID" -o "$SCRATCH/epic.json"
+```
+
+`decisions` is the list, each with `id`, `n`, `text` and `superseded_by`. Everything else in §4
+holds: stop mid-round, put both sentences in front of him, say which you think should win and
+why, wait. The loser is superseded by the winner's row id:
+
+```bash
+curl -sS --max-time 30 -X PATCH "http://127.0.0.1:$PORT/api/backlog/decision/$OLD_ID" \
+  -H 'content-type: application/json' -d "{\"superseded_by\":$NEW_ID}"
+```
+
+A superseded decision is never deleted — the record of a reversal is worth more than a tidy list
+— and every story of this epic sees the reversal at once, which is the reason it lives here.
+
+Resuming after a dead terminal is the same as anywhere: re-fetch the epic, read its rounds and
+decisions, carry on at the next number, and say where you are picking up from.
+
+## 4. Propose the tree, and wait
+
+Only when the rounds have stopped. One message, in his language:
+
+- the epic, one line;
+- the stories, in the order they would be done — **title, then one line saying what it is**;
+- under each, the dependency when there is one: *needs the first one done*;
+- what you have deliberately left out, if anything, one line.
+
+No numbering scheme of your own — k0 gives every story a key the moment it exists,
+and inventing a second one now only makes two things to reconcile.
+
+Then ask for the tree as a whole, with `AskUserQuestion` under the rules in §3 of `rounds.md`:
+approve it, change it, or cut something. Expect him to move things. Rework the list and ask
+again; two passes here are cheap and thirty wrong stories are not.
+
+**If the tree comes out longer than about twelve stories, say so before asking.** An epic that
+big is usually two epics, and he decides which.
+
+**Nothing is written until he has said yes.**
+
+## 5. Write it
+
+In this order:
+
+1. **The stories.** One `POST /api/backlog/story` each, with `project_path`, `title`, `body`,
+   `lang`, `epic_key` — the epic's key from step 2 — and a **`prompt`**: the sentence a session
+   opening on that story starts from. Two lines is enough, in his language, and it always says
+   the same two things: what this story is, and that the plan and the standing decisions are on
+   the story, so `/k0-plan K42` or `/k0-work K42` is where to begin. Without it a session started
+   from the board's button opens cold, and ten minutes of discussion reach the terminal by luck.
+   Send each one with `-d @file`.
+2. **The decisions: nothing to do.** They were written on the epic in step 3, as they were taken,
+   and every story carrying `epic_key` inherits them. `GET /api/backlog/story/:id` returns them
+   in the same `decisions` array as the story's own, marked `"owner": "epic"` and labelled
+   `K7·D3`, and `/k0-verify` counter-checks them one by one like any other.
+
+   **Do not copy them down onto the stories.** It is the one thing that looks helpful here and is
+   not: the copy is a second row saying the same sentence, and the day he reverses `K7·D3` on the
+   epic only the epic's changes. The copies stand, and `/k0-verify` goes on holding finished work
+   up against a rule he took back.
+
+   A story only gets a decision of its own when something was settled about *that story* and
+   about no other — usually nothing was, at this point.
+3. **The dependencies.** `POST /api/backlog/dependency` with `{ "story_id": …, "depends_on": … }`,
+   using the ids that came back from step 1.
+
+The epic keeps the record: its `body` is the why, its rounds are the discussion, its decisions are
+the rules. That is what a later `/k0-discuss` on any story in this epic already has in front of
+it, without going looking.
+
+If anything fails, stop and say what got written and what did not. Do not retry blindly and do
+not carry on as if the tree were complete.
+
+## 6. Close it
+
+Short, in his language: the epic's key and title, how many stories, and the one to start with —
+which you get from `/api/backlog/next` — asked the same way as the listing above, with
+`--get --data-urlencode "repo=$REPO"` — and not from your own reading of the list.
+
+## Rules
+
+- **Never write a story before he has agreed to the tree.** This is the rule the skill exists
+  for.
+- **Everything he says is stored in the language he said it in.** Titles, bodies, decisions.
+  The interface stays English; his words do not get translated.
+- **Never ask for what the API already knows** — keys, states, an epic's progress,
+  what is blocked. `rounds.md` §7 has the table.
+- **Decisions are written the way `rounds.md` §5 says**, and at the ceiling the discussion stops
+  the way §2 says. Neither rule is repeated here, and neither is yours to soften.
+- **No files outside the scratch directory**, and never a `git` command that changes anything.

package/.claude/skills/k0-links/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "k0-links",
+  "version": "0.1.0",
+  "author": { "name": "Alessio Ragni", "url": "https://alessioragni.com" },
+  "description": "While k0 is running, the addresses, folders, documents and artifacts the last reply named sit above the prompt, one click away"
+}

package/.claude/skills/k0-links/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.js"] }