From f3ccbd86f93a5af49e060e89b413f210c327f765 Mon Sep 17 00:00:00 2001 From: Torben Nehmer Date: Sat, 3 Oct 2026 23:03:10 +0200 Subject: [PATCH] feat: participation and RACI labels, written on the project page (#118) Files changed: - CHANGES.md - VERSION - instructions/gtd-weekly-review/SKILL.md - instructions/link-taxonomy.md - kb/entities/COLLECTION.md - kb/gtd/COLLECTION.md - types/project.md Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2 --- CHANGES.md | 19 ++++++++++++- VERSION | 2 +- instructions/gtd-weekly-review/SKILL.md | 10 ++++--- instructions/link-taxonomy.md | 37 +++++++++++++++++++++++-- kb/entities/COLLECTION.md | 9 +++++- kb/gtd/COLLECTION.md | 27 +++++++++++++----- types/project.md | 23 +++++++++++---- 7 files changed, 105 insertions(+), 22 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 2ccb9ca..c226afb 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -59,7 +59,7 @@ concern - readable here, never shipped as something to parse. --- -## 8.0.0-beta.33 - 2026-10-03 - The test suite no longer ships, and dist upgrade deletes what a release stops shipping +## 8.0.0-beta.34 - 2026-10-03 - Link-Katalog: Beteiligungs- und RACI-Label von der Projektseite aus **Author:** Torben Nehmer @@ -104,6 +104,7 @@ concern - readable here, never shipped as something to parse. - raw fetch: a sanctioned intake for a URL into incoming/ - new: a subtype gets its own page skeleton from types/..md - The test suite no longer ships, and dist upgrade deletes what a release stops shipping +- Link-Katalog: Beteiligungs- und RACI-Label von der Projektseite aus **Low impact** - version bump no longer points at version release in its output @@ -146,6 +147,22 @@ concern - readable here, never shipped as something to parse. - Page-material passages in type-spec.md, type-guidance.md and language-boundaries.md name subtype templates +### Link-Katalog: Beteiligungs- und RACI-Label von der Projektseite aus + +Der Katalog hatte für Beteiligung kein Label - nur `owns`, `maintains` und `authored`, alle von der +Person aus, und wer mitwirkt, ohne einzustehen, landete bei `owns` (zu stark) oder `see-also` +(nichtssagend). Neu in `instructions/link-taxonomy.md` § Operational: `involves` (beteiligt, Rolle +offen) und die RACI-Label `staffed-by`, `owned-by`, `consults`, `informs`. Sie werden **auf der +Projekt- bzw. Codebase-Seite** geschrieben und zeigen auf Person oder Organisation, weil dort die +Frage „wer ist beteiligt?" gestellt wird und eine Seite nur ihre eigenen Kanten im Links-Block +zeigt. `owned-by` ist die Gegenrichtung von `owns` - die vierte Inversen-Paarung - statt eines +zweiten Wortes für dieselbe Aussage. `kb/gtd/COLLECTION.md` und `kb/entities/COLLECTION.md` +autorisieren `involves` und `owned-by`; die RACI-Label nimmt eine Instanz für Kundenprojekte in +ihre eigene `COLLECTION.md` auf. `types/project.md`, `kb/gtd/COLLECTION.md` und der Skill +`gtd-weekly-review` sagen jetzt, was mit einer Person in `## Beteiligte` passiert, sobald sie eine +eigene Seite hat: Wikilink auf die Erwähnung, Kante auf der Projektseite. Kein Code kennt die +Label; eine bestehende Instanz merkt nichts, bis sie eines autorisiert (Gitea #118). + ### The test suite no longer ships, and dist upgrade deletes what a release stops shipping `dist export` used to ship all of `tools/chemenu/tests/` with `tools/pytest.ini` and diff --git a/VERSION b/VERSION index d85f03f..2fb7f59 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -8.0.0-beta.33 +8.0.0-beta.34 diff --git a/instructions/gtd-weekly-review/SKILL.md b/instructions/gtd-weekly-review/SKILL.md index 8d686b6..3baa1f0 100644 --- a/instructions/gtd-weekly-review/SKILL.md +++ b/instructions/gtd-weekly-review/SKILL.md @@ -72,10 +72,12 @@ surface, lives in `docs/knowledge-and-commitment.md`, which this skill does not skill exists precisely because that join is not automatic. 4. **Mentions of people stay mentions.** A person named in `## Beteiligte` while working through a - finding does **not** get a page or a `[[wikilink]]`, however much this pass is about them - a - page is earned only once they matter for the knowledge independent of this one initiative - (`types/project.md` § Authoring guidance). Creating one here, out of the habit of linking what - gets mentioned, is the mistake this step exists to head off. + finding does **not** get a page, however much this pass is about them - a page is earned only + once they matter for the knowledge independent of this one initiative (`types/project.md` + § Authoring guidance). Creating one here, out of the habit of linking what gets mentioned, is + the mistake this step exists to head off. Someone who already has a page is the other case, + and the same section says what it takes: a `[[wikilink]]` on the mention and a participation + edge on the project page. 5. **Close out.** If any page changed, `instructions/publish-cycle.md`. A pass that only changed tracker state (the user acted on option (a)/(b) above without touching `kb/`) publishes diff --git a/instructions/link-taxonomy.md b/instructions/link-taxonomy.md index cb1898b..6987030 100644 --- a/instructions/link-taxonomy.md +++ b/instructions/link-taxonomy.md @@ -59,9 +59,9 @@ edge merely to mirror the first one.** The inbound view is rendered from the gra `index rebuild` and `search`, so a reader landing on the target sees what points at it whether or not anyone wrote a second edge. -That is why most labels below have no inverse. Only three pairs do, because in each the reverse +That is why most labels below have no inverse. Only four pairs do, because in each the reverse direction is a genuine primary statement someone would write on its own: `depends-on` / -`required-by`, `runs-on` / `hosts`, and `composition` / `part-of`. +`required-by`, `runs-on` / `hosts`, `composition` / `part-of`, and `owns` / `owned-by`. **A self-dual label is still written once.** `alternative-to` is its own inverse - the sentence reads identically from either end - and that makes it the easiest label in the catalogue to @@ -82,6 +82,15 @@ relationship the catalogue already had a word for. It is not a mirror: the paren lists its parts, the child's names the whole it belongs to, and a reader landing on the child needs the second one. +The fourth came with the participation labels, and for the opposite reason: not a child reaching +for a word, but a page whose reader asks the question from the other end. "Who answers for this +initiative?" is asked on the initiative's page, and a page shows only the edges it carries itself - +the inbound view lives in `search` and the index, not in the page's own links block. So the +initiative writes `owned-by`, a person page may still write `owns`, and neither is a mirror of the +other: each answers a reader who is standing where the edge is written. A new name for the same +claim would have been the alternative, and the worse one - two words for one statement are a +synonym no `lint` can tell apart, where an inverse pair is one statement read from either end. + ## When to run Adding or changing a `related:` entry, authorising labels in a `COLLECTION.md`, or judging @@ -128,8 +137,13 @@ entity to entity. | `produces` | — | emits the target as an artifact or data | | `consumes` | — | reads the target as an artifact or data | | `maintains` | — | carries the upkeep of the target | -| `owns` | — | is accountable for the target's existence and decisions | +| `owns` | `owned-by` | is accountable for the target's existence and decisions | +| `owned-by` | `owns` | has in the target the one accountable for its existence and decisions | | `authored` | — | created the target as a one-time act | +| `involves` | — | takes the target in as a participant, without naming its role | +| `staffed-by` | — | is carried out, in part, by the target's work | +| `consults` | — | draws on the target's judgment without the target carrying the work | +| `informs` | — | keeps the target informed, without the target taking part | | `alternative-to` | itself | serves the same purpose as the target, so a reader choosing between them wants both | `uses` versus `depends-on` is the distinction worth keeping sharp: if removing the target breaks @@ -141,6 +155,23 @@ says someone answers for this thing now - so it reads false about a person who i gone from the project, however plainly they made it. That is the case `authored` exists for, and picking `owns` for it is not a weaker edge but a wrong one. +`involves`, `staffed-by`, `owned-by`, `consults` and `informs` are the participation labels, and +they are written from the other end: on the initiative, codebase or system, pointing at whoever +takes part - `[Initiative] consults [Anna Müller]`. That is where "who is involved?" gets asked, +and a page's own links block shows only the edges it carries. The target may be a person or an +organization; "staffed-by Contractor GmbH" reads as true as "staffed-by Anna Müller". Four of them +are RACI read as sentences - `staffed-by` the R, `owned-by` the A, `consults` the C, `informs` +the I - and `involves` is the one to take when the role is not worth stating or not known. +It is the general label of the five and the weaker one: where a RACI label is true, take it +instead (see Decision points). `owned-by` and `staffed-by` are the pair most easily confused - the +one answers for the outcome, the other does the work, and a single person can be both, which is +two edges, not a choice between them. + +A collection authorises whichever of the five its pages need. A household wiki may run on +`involves` and `owned-by` alone; one tracking client projects may authorise the four RACI labels +and drop `involves`. Someone only mentioned - neither working, consulted nor informed - takes no +edge at all (step 1). + `alternative-to` versus `contrasts` versus `compares-with`: `contrasts` asserts a *difference worth reading both for*, `alternative-to` asserts *substitutability* - two things a reader might pick between for the same job. `compares-with` weighs them on named dimensions, which in this diff --git a/kb/entities/COLLECTION.md b/kb/entities/COLLECTION.md index ec488bb..18f135e 100644 --- a/kb/entities/COLLECTION.md +++ b/kb/entities/COLLECTION.md @@ -1,7 +1,7 @@ --- profile: entities outbound: - entities: [depends-on, required-by, runs-on, hosts, uses, produces, consumes, maintains, owns, authored, alternative-to, implements, part-of, composition, supersedes, derived-from, adapted-from, see-also] + entities: [depends-on, required-by, runs-on, hosts, uses, produces, consumes, maintains, owns, owned-by, authored, involves, alternative-to, implements, part-of, composition, supersedes, derived-from, adapted-from, see-also] concepts: [implements, exemplifies, rests-on, applies-when, operates-on, invokes, authored, alternative-to, see-also] sources: [evidenced-by, defined-in, see-also] comparisons: [compares-with, see-also] @@ -66,6 +66,13 @@ mirrored clique grows fastest. `derived-from` and `adapted-from` are here for th re-implementation - one tool worked up out of another - which is a lineage claim the operational labels cannot make. +`involves` and `owned-by` are the participation labels, and they run the other way from +`authored`/`owns`/`maintains`: written on the codebase or system, pointing at the person or +organization - `[Codebase] involves [Person]`. `involves` is the contributor who neither answers +for the thing nor keeps it running; take `maintains` or `owns` from the person's side when one of +those is true instead. `owned-by` is `owns` read from the thing's side - write whichever page a +reader would ask the question on, not both by reflex. + Adding a label here is a deliberate contract change, not a way around a refusal. ## Outbound linking diff --git a/kb/gtd/COLLECTION.md b/kb/gtd/COLLECTION.md index be76a9c..81fa4a7 100644 --- a/kb/gtd/COLLECTION.md +++ b/kb/gtd/COLLECTION.md @@ -1,7 +1,7 @@ --- profile: none outbound: - entities: [see-also] + entities: [involves, owned-by, see-also] concepts: [see-also] sources: [see-also] gtd: [see-also] @@ -53,15 +53,28 @@ their own. The initial three values are this instance's own starting vocabulary - **`## Beteiligte` carries mentions, not links (D28).** One to two lines per person, in prose, with no `[[wikilink]]` and no page of their own. This is a deliberate, named exception to `kb/CONTRACT.md` § "Every page should" - a project page with unlinked people in its - `## Beteiligte` section is conforming, not incomplete. A person earns their own page, and the - mention becomes an edge, only once they matter for the knowledge independent of this one - initiative. + `## Beteiligte` section is conforming, not incomplete. A person earns their own page only once + they matter for the knowledge independent of this one initiative. From then on the exception + no longer covers them: the mention stays, gains a `[[wikilink]]`, and the project page - this + one, not the person's - carries the edge (see Authorised labels). ## Authorised labels -Only `see-also` is authorised in every direction for now. The vocabulary a participation edge -(person -> project) would use is a deliberate later addition, not an oversight - adding it is a -collection-contract change made when that label exists, not a way around a refusal. +Participation is written on the project page, pointing at the person or organization: +`[Projekt] involves [Person]`. The page is where "who is involved?" gets asked, and a page's own +links block shows only the edges it carries. Two labels are authorised for it, drawn from +[instructions/link-taxonomy.md](../../instructions/link-taxonomy.md) § Operational: + +- `involves` - takes part, role not stated. The default for a household initiative. +- `owned-by` - the one who answers for the initiative's existence and decisions; the inverse of + `owns`, which a person page may still carry independently. + +The catalogue also holds the RACI labels `staffed-by`, `consults` and `informs`. This instance +does not authorise them - its initiatives are too small for the distinction to earn its upkeep - +but an instance tracking client work adds them here, a deliberate contract change like any other. + +Every other direction is `see-also` only for now. Adding a label is a collection-contract change, +not a way around a refusal. ## Outbound linking diff --git a/types/project.md b/types/project.md index 652c42e..58a4ab6 100644 --- a/types/project.md +++ b/types/project.md @@ -18,6 +18,17 @@ This instance's configuration for the `project` type: its frontmatter fields as requires them, and the page skeleton `wikitool new project` scaffolds. `project` is instance-owned end to end - it declares no `guidance:`, so this file's own prose (below) carries its authoring contract, the same way a type an instance invents for itself always does. + + +## Contents + +- [When to use](#when-to-use) +- [When NOT to use](#when-not-to-use) +- [Frontmatter](#frontmatter) +- [Authoring guidance](#authoring-guidance) +- [Template](#template) + + ## When to use - A committed initiative in the GTD sense: something with a goal, an end state, and open loops - @@ -54,10 +65,12 @@ contract, the same way a type an instance invents for itself always does. synced (`AGENTS.md` invariant 8 - one truth about "status"). - **`## Beteiligte` carries mentions, not links.** One to two lines per person, in prose, with **no `[[wikilink]]` and no page of their own.** A person earns a page only once they matter for - the *knowledge*, independent of this project - at that point the mention becomes an edge with a - participation label. This is a deliberate, named exception to `kb/CONTRACT.md` § "Every page - should" (link to the entities it mentions): it is held by this rule, not by a checker, so read - a page here with no person-links as conforming, not as incomplete. + the *knowledge*, independent of this project - from then on the mention keeps its line, gains a + `[[wikilink]]`, and this project page carries a participation edge to the person (`involves`, + `owned-by` - whichever `kb/gtd/COLLECTION.md` authorises). This is a deliberate, named exception + to `kb/CONTRACT.md` § "Every page should" (link to the entities it mentions), covering only + people without a page: it is held by this rule, not by a checker, so read a page here with no + person-links as conforming, not as incomplete. ## Template @@ -81,7 +94,7 @@ TODO: Warum jetzt, warum überhaupt - der Hintergrund, der nicht aus dem Titel f ## Beteiligte -TODO: Ein bis zwei Zeilen je Person - Erwähnung im Fließtext, kein Wikilink, keine eigene Seite. +TODO: Ein bis zwei Zeilen je Person - Erwähnung im Fließtext. Ein Wikilink nur, wenn die Person eine eigene Seite hat; dann trägt diese Seite auch die Kante (`involves`/`owned-by`). ## Status