feat: Issue-Board auf vier Pflicht-Label-Familien und Body-als-Wahrheit (#41)

Files changed:
- CHANGES.md
- VERSION
- instructions/dev/issue-tracking.md
- instructions/dev/stack-dev/SKILL.md

CHANGES.md

@@ -20,6 +20,44 @@ their date-only headings.
 
 ---
 
+## 4.0.1 - 2026-09-02 - Issue-Board: vier Pflicht-Label-Familien und Body-als-Wahrheit
+
+**Author:** Torben Nehmer
+
+Das Issue-Schema aus 1.2.1 hatte zwei Pflichtachsen und einen ausdrücklich begründeten Verzicht
+auf eine dritte: eine Taxonomie mit mehr Achsen brauche eigene Pflege, und das Board habe einen
+einzigen Betreuer. Diese Begründung ist entfallen, weil die Pflege inzwischen maschinell
+passiert - Body-Rewrites und Kommentare laufen über eine LLM-Sitzung, Menschen fassen in der
+Regel nur Labels an. Damit sind vier Achsen bezahlbar (Issue #41).
+
+**Pflicht auf jedem offenen Issue sind jetzt vier Label:** `area/` (`kb`, `distribution`,
+`corpus`, `workflow`, `process` - kein `area/tools`, Tooling wird nach der bedienten Domäne
+einsortiert, nicht nach Codeort), `kind/` (`decision`, `build`, `defect`), `prio/`
+(`blocking`, `planned`, `waiting` - reine Umbenennung von `1`/`2`/`3`) und `size/` (`S`, `M`,
+`L`; `XS` entfällt). Dazu zwei optionale Flags: `status/blocked` für Abhängigkeit von einem
+anderen offenen Issue, `status/unconfirmed` für einen ungeprüften Verdacht, unter dem `size`
+und `prio` vorläufig sind. Ein `unconfirmed`-Issue endet in der Triage entweder ohne Flag und
+mit verbindlichen Werten oder geschlossen mit Begründung - die Prozessentsprechung zu
+Invariante 3.
+
+**Der Issue-Body ist ab jetzt aktuelle Wahrheit, nicht Ursprungstext.** Die Umsetzung eines
+Issues zieht sich über mehrere, zeitlich getrennte Sitzungen, und der Body ist das einzige, was
+sie verbindet: eine Sitzung muss aus ihm allein rekonstruieren können, was entschieden und was
+offen ist. Er wird deshalb umgeschrieben statt ergänzt. Jeder Rewrite bekommt einen Kommentar,
+der ausschließlich benennt, was sich geändert hat - keine Vollkopie des alten Stands, weil ein
+Mensch zwei Fließtexte nicht diffen kann und eine Kopie pro Revision damit keine Historie ist,
+sondern nur eine weitere Kopie.
+
+Geändert: [instructions/dev/issue-tracking.md](instructions/dev/issue-tracking.md) (Schritte 2,
+3, 5 neu; Schritt 4 um `area/` und `kind/` erweitert; der Entscheidungspunkt „Two labels feel
+too coarse?" entfällt) und die Beschreibungszeile in `instructions/dev/stack-dev/SKILL.md`. Für
+eine ausgelieferte Instanz ändert sich nichts: `dist export` schließt `instructions/dev/`
+vollständig aus, weshalb dies ein PATCH ist und kein MINOR - dieselbe Begründung wie bei
+`1.2.1`. Noch offen aus #41: `kb/concepts/Issue Label Scheme.md` beschreibt weiterhin das
+zweiachsige Schema und braucht eine eigene `wiki-manage`-Sitzung.
+
+---
+
 ## 4.0.0 - 2026-09-02 - Prosa ist kein Identifier: Link-Taxonomie als Enum, generierte Regionen mit Markern
 
 **Author:** Torben Nehmer

VERSION

@@ -1 +1 @@
-4.0.0
+4.0.1

instructions/dev/issue-tracking.md

@@ -1,7 +1,7 @@
 ---
 type: types/instruction.md
 name: issue-tracking
-description: Where open work on this stack is tracked, and what the prio/ and size/ labels on a Gitea issue mean.
+description: Where open work on this stack is tracked, what the four mandatory area/kind/prio/size labels and the two status flags on a Gitea issue mean, and how to keep an issue body current across sessions.
 ---
 # Track open work as Gitea issues, not as prose in the repo
 
@@ -26,6 +26,8 @@ issues at that URL, which is exactly why `dist export` excludes
   the repo.
 - A session's findings outgrow the change it was making - a gap in the tooling,
   an assumption nobody has checked, a decision that needs the user.
+- Picking an issue up: before doing anything else, read the body as the current
+  spec, and re-label it if the ground has moved since.
 - Prioritising: deciding what to pick up next, or re-labelling after the ground
   moved.
 
@@ -36,35 +38,96 @@ issues at that URL, which is exactly why `dist export` excludes
    specific files or commands involved. An issue that only makes sense to
    whoever wrote it is a note, and notes were the problem.
 
-2. **Give it exactly two labels: one `prio/`, one `size/`.** Both, always -
+2. **Treat the body as the current truth, not as a historical first post.**
-   a priority without a cost is half a decision. Neither is a promise about
+   Work on one issue spans several sessions, often weeks apart, and the body is
-   *when*; together they answer "what should I pick up in the time I have".
+   the only thing that connects them: a session opening the issue must be able
+   to reconstruct what is decided and what is still open from the body alone,
+   without a human re-explaining it. So when the state changes, **rewrite the
+   body** - do not append to a text that has become wrong. An additively grown
+   log forces every later reader to reconstruct the current state by filtering
+   the whole history.
 
-   | Priority | Means |
+   Body rewrites and comments are an LLM session's job. A human normally
+   touches only labels and metadata directly.
+
+3. **Comment a changelog, never a copy.** Every body rewrite gets one short
+   comment naming only what changed against the previous state - what is new,
+   what is gone, what was corrected. Do not snapshot the old body into a
+   comment: a full copy per revision forces a human to diff two prose texts,
+   which is not a readable history, only another copy.
+
+   ```
+   **Changelog:** Decision 2 tightened - `kind/` may now change over an
+   issue's life. Old acceptance criterion 3 dropped (covered by #42).
+   ```
+
+4. **Give it all four mandatory labels: one `area/`, one `kind/`, one `prio/`,
+   one `size/`.** All four, always. Machine maintenance by an LLM session is
+   what makes four axes affordable - the original objection to a third and
+   fourth axis was the upkeep cost for a single human maintainer, and that
+   objection no longer holds.
+
+   | `area/` | Means |
    |---|---|
-   | `prio/1` | Blocks or damages work in progress. Next. |
+   | `area/kb` | The `kb/` schema, contract, confidence machinery, lint - the knowledge base as a system. |
-   | `prio/2` | Accrues interest. Planned. |
+   | `area/distribution` | Shipping, upgrading and versioning an instance. |
-   | `prio/3` | Worth doing, waiting on a trigger. |
+   | `area/corpus` | The content and scope of `kb/` in this instance, and the demo/testbed question. |
+   | `area/workflow` | Git, merging, branching, publish, PRs. |
+   | `area/process` | The development process itself, rather than the stack as an artefact. |
 
-   `prio/3` is not a graveyard. It means the issue's value is real but gated on
+   There is deliberately no `area/tools`: tooling is filed under the domain it
-   something outside it - a decision, another issue, a second instance
+   serves, not under where its code sits. The axis follows the stage split in
+   [AGENTS.md](../../AGENTS.md).
+
+   | `kind/` | Means |
+   |---|---|
+   | `kind/decision` | Waiting on an operator decision. |
+   | `kind/build` | Specified; waiting only on implementation time. |
+   | `kind/defect` | A finding: documentation and reality, or two documents, contradict each other. |
+
+   `kind/` is expected to change over an issue's life - `decision` becomes
+   `build` once the decision is made. That is session memory working, not a
+   labelling failure.
+
+   | `prio/` | Means |
+   |---|---|
+   | `prio/blocking` | Blocks or damages work in progress. Next. |
+   | `prio/planned` | Accrues interest. Planned. |
+   | `prio/waiting` | Worth doing, waiting on a trigger. |
+
+   `prio/waiting` is not a graveyard. It means the issue's value is real but
+   gated on something outside it - a decision, another issue, a second instance
    existing. Name that trigger in the issue, or the label is a polite no.
 
-   | Size | Means |
+   | `size/` | Means |
    |---|---|
-   | `size/XS` | Minutes. Often just a decision or an observation to record. |
    | `size/S` | One session, one publish, a clear cut. |
    | `size/M` | Several files; a contract or instruction change; its own test effort. |
    | `size/L` | Several sessions, or open design questions before the first commit. |
 
-   Size is effort, not importance. A `prio/1 size/XS` is the best thing on the
+   Size is effort, not importance. A `prio/blocking size/S` is the best thing
-   board; a `prio/3 size/L` is a thing to talk about before anyone starts.
+   on the board; a `prio/waiting size/L` is a thing to talk about before anyone
+   starts.
 
-3. **Re-label when the ground moves, and say why in a comment.** A trigger that
+5. **Add a `status/` flag only when it applies.** Both are optional, because
-   fired turns `prio/3` into `prio/2`. A design question that got answered can
+   each describes a temporary condition rather than a property every issue has.
-   drop a size. Silent re-labelling is how a board stops meaning anything.
 
-4. **Close with what actually happened**, not with a commit hash alone: which
+   | `status/` | Means |
+   |---|---|
+   | `status/blocked` | Waiting on another, still-open issue - not workable on its own, whatever its `prio/` says. Name the blocking issue in the body. |
+   | `status/unconfirmed` | A reported suspicion, not yet checked against actual behaviour. Applies to any `kind/`, not just `kind/defect`. |
+
+   While `status/unconfirmed` is set, `size/` and `prio/` are provisional. Triage
+   ends it one of two ways: the flag comes off and `size`/`prio` are set for
+   real, or the issue is closed with the reason. An unverified suspicion does not
+   stay open indefinitely - the process-level analogue of AGENTS.md invariant 3.
+
+6. **Re-label when the ground moves, and say why in a comment.** A trigger that
+   fired turns `prio/waiting` into `prio/planned`. A design question that got
+   answered can drop a size and move `kind/decision` to `kind/build`. Silent
+   re-labelling is how a board stops meaning anything.
+
+7. **Close with what actually happened**, not with a commit hash alone: which
    proposals were implemented, which were deliberately left out and why, and
    what was verified. The issue is the only place that record survives - a
    changelog entry says what changed, not what was decided against.
@@ -75,8 +138,13 @@ issues at that URL, which is exactly why `dist export` excludes
   what shipped. A finished change needs both: the entry, and the issue closed
   with the reasoning.
 - **Issue or `kb/` page?** An issue is about *this stack* and is ephemeral - it
-  closes. A `kb/` page is compiled knowledge that stays true. Never put wiki
+  closes, and it records a wish. A `kb/` page is verified knowledge that stays
-  content findings in an issue, and never file a work item as a page.
+  true. Never put wiki content findings in an issue, and never file a work item
-- **Two labels feel too coarse?** They are meant to. A third axis - kind, area,
+  as a page.
-  status - is the point at which a taxonomy starts needing maintenance of its
+- **Rewrite the body, or add a comment?** Rewrite whenever a reader of the body
-  own, and this board has one maintainer.
+  alone would otherwise be misled - a changed decision, a dropped criterion, a
+  new constraint. A comment carries the changelog line for that rewrite, and
+  nothing else that a future session needs in order to act.
+- **An old issue carries only `prio/` and `size/`?** Complete it to all four
+  when you touch it, rather than in a sweep. The board reaches the new scheme
+  issue by issue, as each is picked up.

instructions/dev/stack-dev/SKILL.md

@@ -43,8 +43,9 @@ stack development happens in the origin repo instead (see AGENTS.md's routing li
    engineering, memory and deploy-time learning; consult before a design decision in those
    areas.
    [issue-tracking.md](../issue-tracking.md) - open work lives in Gitea issues, one per work
-   package, labelled `prio/1..3` and `size/XS..L`. There is no `TODO.md`. Read it before
+   package, labelled `area/`, `kind/`, `prio/` and `size/`, with the body kept as the current
-   filing something for later, or before deciding what to pick up next.
+   truth rather than as a first post. There is no `TODO.md`. Read it before filing something
+   for later, before editing an issue, or before deciding what to pick up next.
    [testing-conventions.md](../testing-conventions.md) - the suite runs against a deliberately
    empty machine; what the autouse fixture already neutralizes, and what a test still has to
    establish itself. Read it before adding or changing a test.