feat: model context sources in BPMN

.agents/agents/agentic-artifact-reviewer.md

@@ -27,6 +27,12 @@ A directory (usually `generated/<workflow>/`) or a list of files. For generated
    and loop from the spec appears with its condition and `maxLoops` behaviour; every human
    checkpoint uses options plus a recommendation; side effects come after their checkpoint; a
    Workflow script passes each `agent()` the paths and constraints it needs.
+   Where the spec has `contextSources`, also check: a live-store write in a step with no
+   `userTask` before it (`design`); tool lists (`tools:`, `permissions.allow`) broader than the
+   lane's stores need, wildcards, or write tools in read-only lanes (`design`); a memory store whose
+   text lacks the fixed sections or whose cap hook is missing (`generate`); a step that needs
+   knowledge but whose `## Kontextquellen` section or `references/` lacks the store (`generate`);
+   a store in the spec that no step reads (`design`).
 3. Respect the pipeline's own conventions — `bpmn:` frontmatter, verbatim BPMN labels inside
    English text, the templates' regenerate boundary, the JSON reporting block. They are not
    findings.

.agents/agents/agentic-workflow-architect.md

@@ -24,6 +24,11 @@ If a rubric is missing, say so in `summary` and skip rubric checks.
    `artifacts`, `openQuestions`, `knowledge`.
 2. Run orchestration-design's review mode, and agent-authoring's split rule and tool/model
    guidance per role. Every unanswered or weakly answered question is a finding.
+   For `contextSources`, also flag: a write into a `live` store with no `userTask` before it on
+   every path (`bpmn`); `live` tool lists broader than the lane needs, i.e. wildcards or write tools
+   in a read-only lane (`design`); a `gedaechtnis` store without a writer, a reader or `maxLines`
+   (`bpmn` or `design`); a task that needs knowledge but has no store input (`question`); a store
+   with no `readers` (`question`).
 3. Classify each finding's route: `design` (fixable in the spec), `bpmn` (the diagram must
    change — goes to the user, loop A) or `question` (needs a business decision).
 

.agents/skills/agentic-workflow-kb/references/multi-agent-handoffs.md

@@ -53,6 +53,15 @@ wrong falls back to one sequential agent with shared context
 | Role confusion from overloaded prompts | single responsibility, third-person descriptions for routing [multi-agent-handoffs-1: 50, 77–82] |
 | Cost explosion | zero-token script orchestrators, small models for routine steps, prompt caching, concurrency caps [multi-agent-handoffs-1: 15, 19, 44, 83–88] |
 
+## Context sources at handoff (repo design decision)
+
+Not notebook-cited; from `docs/plans/kontextquellen/plan.md`. Artifacts carry one run's handoff;
+data stores carry what outlives a handoff or a run. A role reads the stores it needs (knowledge
+reference, live tool, memory file) instead of receiving them pasted in the handoff, and its tool
+list names only those stores' tools. Where lanes are not agents, the read tools are shared and the
+plan says so. Memory is a curated file with a line cap that the writing step rewrites, never an
+append-only log.
+
 ## For bpmn2agent
 
 BPMN data objects become `artifacts.<id>` contracts (path + frontmatter) — this is the

.agents/skills/agentic-workflow-kb/references/process-to-agents.md

@@ -15,6 +15,7 @@ Distilled from FAQ `process-to-agents-1`, with the element table from
 | Parallel branches | parallel subagents, merged downstream | [process-to-agents-1: 18–21] |
 | Human approval | HITL checkpoint (pause/resume, edit arguments) | [process-to-agents-1: 22–25] |
 | Data artifact | typed state, memory store or persistent file | [process-to-agents-1: 12, 21, 26, 27, 28] |
+| Data store (cylinder) | context source: knowledge reference, live tool access or memory file, by `Art:` | repo design decision, not notebook-cited |
 
 ## Where each part belongs
 
@@ -54,6 +55,14 @@ extraction, classification and routine calls. A small model can propose, a stron
 
 ## For bpmn2agent
 
+**Data stores (repo design decision, from `docs/plans/kontextquellen/plan.md`; not notebook-cited).**
+A data store is a context source with an `Art:` (`wissen` → cited reference loaded at generation,
+`live` → tool allowlist read at run time, `gedächtnis` → curated memory file with a line cap) and
+an `Ort:`; the arrow direction alone says read or write. Every write into a live store needs a
+`userTask` before it plus an `ask` hook behind it, and a phase with such a write is never a
+workflow script. Ask during design: does each task have a store for what it must know, and does
+each store have a reader?
+
 This confirms the pipeline's defaults (lane → agent, service task → skill or checklist item,
 script task → script, gateway → orchestrator logic, user task → checkpoint, data object →
 artifact contract). The questions to add during design: is this lane really one role or two? Is

.agents/skills/bpmn-authoring/SKILL.md

@@ -5,18 +5,17 @@ description: Creates, extends or refines BPMN 2.0 .bpmn diagrams (process models
 
 # Author BPMN
 
-Diagrams here are descriptive process models (`isExecutable="false"`), documenting how a process
-works. The `references/` are distilled from an external German BPMN reference (not in this repo);
-load each at the step that needs it.
+Diagrams are descriptive process models (`isExecutable="false"`). Load each `references/` file at
+the step that needs it.
 
 ## Workflow
 
 ### 1. Understand the existing file
 
 Read the target file (or start from `assets/skeleton.bpmn`). List its element IDs, sequence flows
 and `BPMNDiagram`/`BPMNPlane` pairs before changing anything. **Never renumber or rename an existing
-ID** — every `sourceRef`/`targetRef`, `dataObjectRef`, `bpmnElement`, `categoryValueRef` would need
-updating, and a missed one is a dangling reference only bpmn-moddle (not xmllint) catches.
+ID**: a missed `sourceRef`/`targetRef`, `dataObjectRef`, `bpmnElement` or `categoryValueRef` becomes
+a dangling reference that only bpmn-moddle (not xmllint) catches.
 
 ### 2. Model the semantics first, layout second
 
@@ -34,10 +33,9 @@ Most-missed:
 
 ### 3. Refining a task into a collapsed drill-down sub-process
 
-1. Change the tag from `bpmn:task` to `bpmn:subProcess`; **keep its `id`**, so everything pointing
-   at it keeps working.
-2. Move its `dataInputAssociation`/`dataOutputAssociation` onto the subProcess element itself (they
-   stay at the collapsed level, not on an inner step).
+1. Change the tag from `bpmn:task` to `bpmn:subProcess`; **keep its `id`**.
+2. Move its `dataInputAssociation`/`dataOutputAssociation` onto the subProcess element itself, not
+   onto an inner step.
 3. Add the inner flow as children: one blank start event, the step tasks, an internal gateway/loop if
    the phase has one, one or more named end events, and their sequence flows. IDs per
    `references/xml-and-di.md`.
@@ -57,10 +55,10 @@ exclusive gateway.
 ${CLAUDE_SKILL_DIR}/scripts/validate.sh <file>.bpmn
 ```
 
-Runs XSD (xmllint) → bpmn-moddle parse warnings → `bpmnlint:recommended --max-warnings=0` and stops
-at the first failing stage. Fix every finding before moving on; `references/validation.md` has what
-each stage catches and a table of typical errors. Tooling is fetched on demand into
-`${BPMN_TOOLS_CACHE:-$HOME/.cache/bpmn-authoring-tools}`; never add it to this repo's `package.json`.
+Runs XSD (xmllint) → bpmn-moddle parse warnings → `bpmnlint:recommended --max-warnings=0`, stopping
+at the first failing stage. Fix every finding before moving on; see `references/validation.md`.
+Tooling is fetched on demand into `${BPMN_TOOLS_CACHE:-$HOME/.cache/bpmn-authoring-tools}`; never
+add it to this repo's `package.json`.
 
 ### 6. Render and eyeball
 
@@ -80,10 +78,10 @@ each one, not in a batch.
 
 ## Files
 
-- `references/xml-and-di.md` — skeleton, element catalogue, drill-down and lane XML/DI, standard sizes.
-- `references/modelling-rules.md` — hard rules, best practices, loops, lanes, naming.
-- `references/layout.md` — the coordinate grid, top-level and per child plane.
+- `references/xml-and-di.md` — skeleton, element catalogue, data stores, drill-down and lane XML/DI,
+  standard sizes.
+- `references/modelling-rules.md` — hard rules, best practices, lanes, loops, German labels.
+- `references/layout.md` — coordinate grid, top-level and per child plane.
 - `references/validation.md` — what each validation stage catches, typical errors and fixes.
-- `assets/skeleton.bpmn` — minimal valid file to start from; `assets/.bpmnlintrc` — the lint config.
-- `scripts/validate.sh` (step 5), `scripts/check-moddle.mjs` (called by it), `scripts/render.mjs`
-  (step 6).
+- `assets/skeleton.bpmn` (starting file), `assets/.bpmnlintrc` (lint config).
+- `scripts/validate.sh` (step 5, calls `scripts/check-moddle.mjs`), `scripts/render.mjs` (step 6).

.agents/skills/bpmn-authoring/references/layout.md

@@ -1,8 +1,7 @@
 # Layout conventions (grid & coordinates)
 
-DI is hand-laid on the grid below (`bpmn-auto-layout` can't produce drill-down planes).
-
-Sizes and why: `xml-and-di.md`, "Standard sizes".
+Lay out DI by hand on the grid below (`bpmn-auto-layout` can't produce drill-down planes). Sizes:
+`xml-and-di.md`, "Standard sizes".
 
 ## Top-level plane grid
 
@@ -16,6 +15,16 @@ Sizes and why: `xml-and-di.md`, "Standard sizes".
 - **Data objects**: `y=170`, height 50, centred above the task that outputs them; labels above them.
   Input associations from an earlier data object route via a waypoint at `y=195` before dropping into
   the consuming task's top edge.
+- **Data stores** (`dataStoreReference`, 50×50): below the task row, inside the lane of their first
+  reader, ~60px under the task bottom, label beside or below the store. Read arrows run straight up
+  into the task's bottom edge. A store that is also written later gets its write arrow routed in a
+  channel below the stores (own `y` per store, ~25px apart) so no two arrows cross; with lanes, put
+  the lane that the happy path leaves and re-enters above the other, so the vertical hops do not
+  cross those channels. Several stores under one task sit side by side.
+- **Process input/output** (`dataInput`/`dataOutput`, 36×50): the input left of the start event, the
+  output right of the end event, both in the data-object band above the task row (`y=170`, or the
+  lane's top band). Route the input's association along `y≈195` into the first consuming task's top
+  edge; route the output's association over the tasks between its producer and the end.
 - **Groups (phase bands)**: `y=40`, `height=500`, from just left of the phase's first task to just
   right of its last, ~30–40px padding; label bounds inside the top of the band.
 - New elements extend this row; never start a second main row.
@@ -43,13 +52,13 @@ Each child plane is an independent coordinate space; don't reuse the parent's co
 
 ## General
 
-- Never let two shapes' bounding boxes overlap (`no-overlapping-elements` is a warning; treat it as
-  an error). When in doubt, add horizontal space rather than stacking vertically.
+- Never let two shapes' bounding boxes overlap (treat the `no-overlapping-elements` warning as an
+  error). When in doubt, add horizontal space rather than stacking vertically.
 - Several loop-backs in one plane (e.g. a three-outcome gateway with two targets): sort them by
-  horizontal span; the shortest runs closest to the row, longer ones further below — same at the top
-  level and in child planes.
-- Escape every name/label/condition for XML (`&` → `&amp;`, `"`, `<`, `>`) — German labels often
-  contain `&`, and an unescaped one fails xmllint with `xmlParseEntityRef: no name`. When generating
-  XML from a script, escape once, centrally.
-- Most planes that validate but look wrong have a coordinate slip: an off gap after inserting a
-  shape mid-row (shift every shape after it), or a waypoint that doesn't touch its shape's border.
+  horizontal span; the shortest runs closest to the row, longer ones further below — top level and
+  child planes alike.
+- Escape every name/label/condition for XML (`&` → `&amp;`, `"`, `<`, `>`); an unescaped `&` (common
+  in German labels) fails xmllint with `xmlParseEntityRef: no name`. When generating XML from a
+  script, escape once, centrally.
+- A plane that validates but looks wrong usually has a coordinate slip: an off gap after inserting a
+  shape mid-row (shift every shape after it), or a waypoint not touching its shape's border.

.agents/skills/bpmn-authoring/references/modelling-rules.md

@@ -19,8 +19,8 @@
   synchronize parallel paths with AND — matching the split type.
 - **Split and merge are separate gateways** (never one gateway with n-in and n-out).
 - **One blank start and at least one end event** per process and per embedded sub-process; no implicit
-  start/end (nodes with no incoming/outgoing). One end event per distinct outcome is fine; name end
-  events after the resulting state.
+  start/end (nodes with no incoming/outgoing). One end event per distinct outcome is allowed; name
+  each after the resulting state.
 - A sub-process without an internal check is a plain `Start → S1..Sn → End` chain; don't add a
   gateway it doesn't need.
 - **Naming**: tasks = verb + object ("Entwurf prüfen"); events = object + past participle / state
@@ -29,8 +29,7 @@
   `label-required` expects names on tasks, events, forking XOR/OR gateways, conditional flows, pools
   and lanes; `superfluous-label` flags names on unconditional flows that don't leave an XOR/OR split
   and aren't default flows.
-- **Groups** only for visual grouping ("Review phase"); they never change behavior and must not stand
-  in for sub-processes.
+- **Groups** only for visual grouping ("Review phase"); never as a stand-in for sub-processes.
 - Avoid inclusive/complex gateways and `terminateEndEvent` unless the semantics are genuinely needed.
 - Flow left to right, happy path on a straight line, no overlapping shapes.
 
@@ -56,8 +55,7 @@ flows (initial entry, loop-back), one outgoing flow into that task. The gateway
 loop is a separate, later XOR **split** gateway after the body, with a question name and named
 outgoing flows (one of them `default`). If the loop returns to the very first step of a sub-process,
 the merge gateway sits between the start event and that step. Same pattern at the top level and
-inside child planes; see `examples/dark-factory/product-vision-to-user-stories.bpmn` in this repo
-for worked examples.
+in child planes; worked examples: `examples/dark-factory/product-vision-to-user-stories.bpmn`.
 
 ## German labels
 

.agents/skills/bpmn-authoring/references/validation.md

@@ -4,9 +4,8 @@
 ${CLAUDE_SKILL_DIR}/scripts/validate.sh <file>.bpmn
 ```
 
-Runs the three stages below in order, stops at the first failing one (a structural XSD failure makes
-later output noise) and exits non-zero. Read the script for the exact commands; tooling is cached in
-`${BPMN_TOOLS_CACHE:-$HOME/.cache/bpmn-authoring-tools}`.
+Runs the three stages below in order, stops at the first failing one and exits non-zero. Exact
+commands are in the script; tooling is cached in `${BPMN_TOOLS_CACHE:-$HOME/.cache/bpmn-authoring-tools}`.
 
 ## Stages
 
@@ -21,22 +20,22 @@ later output noise) and exits non-zero. Read the script for the exact commands;
    `no-disconnected`, `no-implicit-start`/`-end`, `no-implicit-split`, `single-blank-start-event`,
    `sub-process-blank-start-event`, `end-event-required`/`start-event-required` (per scope — every
    sub-process needs its own), `label-required`, `fake-join`, `superfluous-gateway`,
-   `no-overlapping-elements` (the last three are warnings, which still fail at zero tolerance).
+   `no-overlapping-elements` (the last three are warnings; they still fail at zero tolerance).
    Misses: `standard-size` (not in `recommended`) and anything visual.
 
-Then render (SKILL step 6) — the only check for how the planes actually look.
+Then render (SKILL step 6): the only check of how the planes look.
 
 ## Typical errors and fixes
 
 | Symptom | Likely cause | Fix |
 |---|---|---|
-| xmllint: element X not expected | wrong child order | check `xml-and-di.md`'s element order (flow elements before artifacts) |
-| xmllint: duplicate ID | copy-pasted a block without renaming IDs | rename per the `<ParentTaskId>_<suffix>` convention |
+| xmllint: element X not expected | wrong child order | follow `xml-and-di.md`'s element order (flow elements before artifacts) |
+| xmllint: duplicate ID | copy-pasted block with unchanged IDs | rename per the `<ParentTaskId>_<suffix>` convention |
 | xmllint: `xmlParseEntityRef: no name` | unescaped `&` in a name/label | escape it as `&amp;` |
-| moddle: unresolved reference | a flow/association points at an ID that doesn't exist yet, or a rename missed a reference | grep the old ID across the file — `sourceRef`, `targetRef`, `bpmnElement`, `dataObjectRef` |
-| bpmnlint `no-bpmndi` | added a semantic element without its DI shape/edge | every element added to `process`/`subProcess` needs a matching `BPMNShape`/`BPMNEdge` in its plane |
-| bpmnlint `sub-process-blank-start-event` / `single-blank-start-event` | refined a task into a subProcess but forgot the inner start event, or added a second one | exactly one blank `startEvent` per sub-process/process scope |
-| bpmnlint `no-implicit-start`/`-end` | a node has no incoming or no outgoing flow and isn't a start/end event | either it's missing a flow, or it should be a start/end event |
-| bpmnlint `label-required` | a new task, event, forking gateway or conditional flow has no `name` | name it per `modelling-rules.md`'s naming convention |
-| bpmnlint `fake-join` (warn) | a loop-back or merge was wired as two incoming flows into an ordinary task | insert an explicit XOR merge gateway before it |
-| Renders but shapes overlap | coordinate arithmetic mistake | recheck against `layout.md`'s grid, especially after inserting a new element mid-row (every shape after it needs its x shifted) |
+| moddle: unresolved reference | a flow/association points at a missing ID, or a rename missed a reference | grep the old ID across the file — `sourceRef`, `targetRef`, `bpmnElement`, `dataObjectRef` |
+| bpmnlint `no-bpmndi` | semantic element without its DI shape/edge | add the matching `BPMNShape`/`BPMNEdge` in its plane |
+| bpmnlint `sub-process-blank-start-event` / `single-blank-start-event` | missing inner start event after refining a task, or a second one | exactly one blank `startEvent` per sub-process/process scope |
+| bpmnlint `no-implicit-start`/`-end` | a non-start/end node has no incoming or no outgoing flow | add the missing flow, or make it a start/end event |
+| bpmnlint `label-required` | task, event, forking gateway or conditional flow without `name` | name it per `modelling-rules.md` |
+| bpmnlint `fake-join` (warn) | loop-back or merge wired as two incoming flows into an ordinary task | insert an explicit XOR merge gateway before it |
+| Renders but shapes overlap | coordinate slip | recheck against `layout.md`'s grid; after inserting an element mid-row, shift every shape after it |