diff --git a/CHANGES.md b/CHANGES.md index 9a0b018..efa1a20 100644 --- a/CHANGES.md +++ b/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 diff --git a/VERSION b/VERSION index fcdb2e1..1454f6e 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -4.0.0 +4.0.1 diff --git a/instructions/dev/issue-tracking.md b/instructions/dev/issue-tracking.md index 9b64dab..b40928e 100644 --- a/instructions/dev/issue-tracking.md +++ b/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 - - a priority without a cost is half a decision. Neither is a promise about - *when*; together they answer "what should I pick up in the time I have". +2. **Treat the body as the current truth, not as a historical first post.** + Work on one issue spans several sessions, often weeks apart, and the body is + 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. | - | `prio/2` | Accrues interest. Planned. | - | `prio/3` | Worth doing, waiting on a trigger. | + | `area/kb` | The `kb/` schema, contract, confidence machinery, lint - the knowledge base as a system. | + | `area/distribution` | Shipping, upgrading and versioning an instance. | + | `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 - something outside it - a decision, another issue, a second instance + There is deliberately no `area/tools`: tooling is filed under the domain it + 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 - board; a `prio/3 size/L` is a thing to talk about before anyone starts. + Size is effort, not importance. A `prio/blocking size/S` is the best thing + 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 - fired turns `prio/3` into `prio/2`. A design question that got answered can - drop a size. Silent re-labelling is how a board stops meaning anything. +5. **Add a `status/` flag only when it applies.** Both are optional, because + each describes a temporary condition rather than a property every issue has. -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 - content findings in an issue, and never file a work item as a page. -- **Two labels feel too coarse?** They are meant to. A third axis - kind, area, - status - is the point at which a taxonomy starts needing maintenance of its - own, and this board has one maintainer. + closes, and it records a wish. A `kb/` page is verified knowledge that stays + true. Never put wiki content findings in an issue, and never file a work item + as a page. +- **Rewrite the body, or add a comment?** Rewrite whenever a reader of the body + 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. diff --git a/instructions/dev/stack-dev/SKILL.md b/instructions/dev/stack-dev/SKILL.md index df9d0c5..5a60764 100644 --- a/instructions/dev/stack-dev/SKILL.md +++ b/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 - filing something for later, or before deciding what to pick up next. + package, labelled `area/`, `kind/`, `prio/` and `size/`, with the body kept as the current + 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.