@@ -13,7 +13,10 @@ the next `copier update` either reverts them or turns them into a merge
 conflict.
 
 Add project specific build steps to `TaskfileCustom.yaml` instead - note the
-`.yaml` spelling, since only that one is included. Project specific agent
+`.yaml` spelling, since only that one is included. A GitLab pipeline takes
+project specific jobs from `.gitlab-ci-custom.yml` the same way, included when
+that file exists; it can add to a templated job but not redefine one, and
+`.github/workflows/` has no equivalent hook. Project specific agent
 instructions belong in `CLAUDE.md`, which the template never writes and which
 is read alongside these rules. Personal tool permissions belong in
 `.claude/settings.local.json`, which is git-ignored.
@@ -49,6 +52,14 @@ silence the rule for code nobody has looked at. Report it with the
 `template-feedback` skill too, since a rule that is wrong here is usually wrong
 in other projects as well.
 
+One class of that is already settled and needs neither a human nor a report:
+`PLR0913` and `PLR0917` on a signature whose arity a framework fixes rather
+than the author - a plugin constructor with one argument per `PluginParameter`,
+a Click command with one per option. Suppress both on the `def`, with the
+reason above it. Neither escape ruff suggests is available, since keyword-only
+arguments answer `PLR0917` but not `PLR0913`, and folding the arguments into
+one object breaks the one-argument-per-option mapping the framework relies on.
+
 ## Every user visible change gets a changelog entry
 
 `CHANGELOG.md` follows [Keep a Changelog](https://keepachangelog.com/). Add an
 
@@ -63,6 +63,44 @@ the template actually changed, such as a bumped dependency constraint.
 Example files that were deleted after generation can reappear when the template
 changes them. Delete them again.
 
+## What the merge will not tell you
+
+A conflict is raised only where copier could not decide. The cases that cost
+the most time are the silent ones, and both directions have happened:
+
+- **The template's new value is not applied.** The template set
+  `cmem-cmemc` to `^25.3.0` in v7.3.0 and lowered it again to `>=24.2.0` in
+  v8.0.0. Four repositories updated straight through that release and on to
+  v9.6.1, and every one still carried the caret afterwards. No commit in them
+  re-introduced it and no conflict was ever raised. It stayed harmless for a
+  year, until click 8.5 began rejecting an empty colour that cmemc 25 passes
+  through - and then several test suites failed at once with
+  `Unknown color ''`.
+- **This project's value is replaced by the template's.** A project carrying its
+  own `[tool.ruff.lint] ignore` and `per-file-ignores` entries lost them
+  wholesale to the template's shorter lists, and the update appeared to add 409
+  lint findings. They were not debt; the configuration that had silenced them
+  was gone.
+
+So do not read "no conflicts" as "nothing to check". After updating, look at
+`pyproject.toml` deliberately - at dependency constraints, and at every
+list-valued setting, because a list is replaced whole rather than merged
+entry by entry.
+
+The reliable check is to render a throwaway project from the same answers and
+diff against it, which shows both what should have arrived and what should not
+have:
+
+```bash
+copier copy --trust --defaults --vcs-ref <the tag you updated to> \
+  -d project_slug=<slug> -d project_type=<plugin|generic> \
+  gh:eccenca/cmem-plugin-template /tmp/reference
+diff /tmp/reference/pyproject.toml pyproject.toml
+```
+
+Treat a sudden jump in lint findings as suspected configuration loss rather
+than real debt, and check that first.
+
 ## After updating
 
 ```bash
 
@@ -11,8 +11,8 @@ This governs the text a user reads inside eccenca Corporate Memory: the `label`,
 Python docstrings, error messages or identifiers. Those are read by developers
 and follow the ordinary code conventions.
 
-`documentation` is rendered as Markdown, so backticks, `**bold**` and links all
-work. `description` is a single line shown next to the task in the task list.
+`documentation` is rendered as Markdown, so backticks, `**bold**`, links, `##`
+headings and lists all work. `description` is a single line shown next to the task in the task list.
 
 ## Ground every claim in the code
 
@@ -66,6 +66,18 @@ lines. Do not pad a simple task to match a complex one, and do not cut a
 complex one down to match a simple one. A task with three mutually exclusive
 modes genuinely needs more words than one with a single input port.
 
+Mark the beats by length, not by taste. While the block is short - which for
+most tasks it is - write it as one run of paragraphs and let the beats follow
+each other unannounced. Once it passes roughly twenty lines, give each beat a
+`##` heading named after it, so a reader scans for the beat they need instead of
+reading until they find it. The caveats beat is the one that stops working as
+prose first, and reads best as a list with the claim in bold at the front of
+each item.
+
+Letting the length decide is what keeps sibling tasks in one package looking
+like one product. A user meets several of them in a workspace, and two
+documentation styles there read as two different things.
+
 ## Parameters
 
 The first sentence says what the parameter controls. Add further sentences only
 
@@ -46,6 +46,39 @@ use `setup_cmempy_user_access()`. Plenty of existing plugins still call it -
 that is legacy, not a pattern to copy. `cmem-plugin-base` continues to depend
 on `cmem-cmempy` transitively, which does not make it available for new code.
 
+## The plugin identifier
+
+Set `plugin_id` explicitly on every `@Plugin`:
+
+```python
+@Plugin(
+    label="Create thing",
+    plugin_id="cmem_plugin_example-CreateThing",
+    ...
+)
+```
+
+Left unset, it is generated from where the code happens to sit -
+`generate_id(module_path + "-" + ClassName)`, so a task in
+`cmem_plugin_example/tasks/create.py` is called
+`cmem_plugin_example-tasks-create-CreateThing`. A workflow references a plugin
+by that identifier, so moving the module or renaming the class changes the
+identity of an already deployed task and orphans every workflow task built on
+it. That turns an ordinary refactoring into a breaking change, without an error
+anywhere.
+
+Name it `<package_dir>-<Name>`. The prefix carries the weight - it keeps the
+identifier distinct from every other plugin in the same workspace - and
+`<Name>` is the class name, or a shortened form where the class repeats
+something the package name already says: `cmem_plugin_ssh-Download` for
+`DownloadFiles`. An identifier you supply bypasses `generate_id()` and is
+therefore never sanitised, so keep it to `[a-zA-Z0-9_-]` yourself.
+
+**For a task that is already deployed, write down the identifier it generates
+today, verbatim** - work it out with the formula above rather than inventing a
+tidier one. The point of setting the field is to stop the identifier moving; a
+first commit that changes it breaks exactly what it is there to protect.
+
 ## Logging
 
 The base class already provides a logger as `self.log`. Use it:
@@ -65,7 +98,12 @@ formatted string. The `logging` idiom
 `self.log.info("Fetched %s records", count)` raises `TypeError` at runtime, so
 an f-string is the form to use - the ruff rule
 `G004` (logging statement uses f-string) is in the `ignore` list accordingly.
-The same gap is why `self.log` cannot be passed as a `logger` argument.
+There is no `exception()` either, so a failure logged inside an `except` block
+uses `error()` - ruff's `TRY400` asks for `logging.exception` there, and is in
+the `ignore` list for the same reason as `G004`. Do not downgrade the call to
+`warning()` to quieten the rule: that understates a failure that is usually
+about to be re-raised. The same gap is why `self.log` cannot be passed as a
+`logger` argument.
 
 ## The icon
 
@@ -156,6 +194,45 @@ same thing - a parameter here versus a connected input - rather than accepting
 both and picking one at runtime. A boolean or an enum parameter drives the same
 pattern with an `if`/`match` in place of the empty-string check.
 
+### What `execute()` receives
+
+The declaration settles what `inputs` can hold, and the two directions are not
+symmetric.
+
+Under `FixedNumberOfInputs` it never carries **more** than the declared number
+of ports. The workflow editor offers exactly the handlers a task declares, so a
+one-port task cannot be connected to two upstream tasks. Code that warns about
+or trims a surplus is unreachable from a workflow, and it especially must not
+be mentioned in the task's `documentation`: telling a user to avoid a state they
+cannot configure is worse than saying nothing. Calling `execute()` directly from
+Python bypasses the editor entirely, which is why a test - or a code review
+reading the body alone - can "reproduce" the surplus and make a non-issue look
+like a defect.
+
+It can carry **fewer**. A declared port the workflow leaves unconnected is
+absent from the sequence rather than arriving as an empty `Entities`, and
+DataIntegration runs the workflow anyway, so `inputs[0]` raises `IndexError`
+on a task whose one port nobody wired. That case is real, and each task decides
+what it means:
+
+```python
+entities = list(inputs[index].entities) if index < len(inputs) else []
+```
+
+reads an unconnected port as an empty one - the right call when input is an
+optional addition to what parameters already supply. Where the input is the
+whole point, fail with a message naming the cause instead:
+
+```python
+if not inputs:
+    raise ValueError("No input was given.")
+```
+
+Both are used across the fleet. With several declared ports, do not additionally
+assume that a partly connected task keeps each remaining port at its declared
+index; drive the loop from `len(inputs)` or accept only what you can identify
+from the entities themselves.
+
 ## Honouring cancellation
 
 A long-running task must stop when the user cancels the workflow. Check the
@@ -173,7 +250,9 @@ for entity in inputs[0].entities:
 
 The `suppress(AttributeError)` is required, not defensive noise:
 `context.workflow` is absent in some contexts - notably the test contexts - and
-an unguarded check raises there while working in production.
+an unguarded check raises there while working in production. The `inputs[0]` in
+front of it is shorthand for a task whose port is connected; see *What
+`execute()` receives* for the case where it is not.
 
 ## Reporting progress
 
@@ -198,6 +277,54 @@ context.report.update(
   the work is finished shows a user nothing while the task is running, which is
   exactly when they are looking.
 
+## The constructor decides the form, not the decorator list
+
+The `parameters=[...]` list in `@Plugin` reads as the order a user sees on the
+task form. It is not. The descriptor is built by walking
+`inspect.signature(__init__)` and looking each argument name up in the decorator
+list, so the **constructor's argument order is the form's field order** and the
+decorator list is only a lookup table for labels, descriptions and types.
+
+Two things follow:
+
+- Reordering the decorator list changes nothing a user can see, which is
+  unpleasant to debug because the file you edited is the one that looks
+  authoritative. Keep the two lists in the same order and reorder them together,
+  so the source reads the way the form does.
+- A decorator entry whose name matches no constructor argument is **dropped
+  without an error**. A renamed argument therefore silently takes its label and
+  description with it, and the field appears bare rather than missing.
+
+Order the constructor the way the decision reads: a parameter goes before the
+ones that depend on it, and above the flag that switches it on. Reordering is
+safe because the framework instantiates by keyword - but check that nothing
+constructs the class positionally first, which tests often do.
+
+## The one parameter name the task form claims
+
+Do not name a parameter `tags`. Every task dialog carries a "Tags" field for the
+item's own tags, and that widget's value arrives on a plugin parameter of the
+same name in place of the string the parameter declares, so saving the task - or
+any other task action - fails with:
+
+```text
+Invalid value for plugin parameter 'tags' of plugin '<package>-<Task>'.
+Got a nested object with the keys createdItems, selectedItems, but expected a string.
+```
+
+An empty tag list fails just as well, because the widget still posts both keys
+as empty lists. Nothing local catches it: discovery succeeds, the descriptors
+show the parameter present, labelled and typed as a string, and `task check` is
+green - the failure exists only against a deployment, in the dialog.
+
+Name the parameter for what it carries - `notification_tags`, `issue_tags` - and
+keep the user-visible wording in the `label`, which can still read "Tags".
+
+`label` and `description` are **not** claimed, although the dialog shows the
+item's own fields under those names as well. `cmem-plugin-shapes`,
+`cmem-plugin-metadata` and `cmem-plugin-vocab` all ship a parameter called
+`label`, and `cmem-plugin-metadata` one called `description`.
+
 ## A constructor with six or more parameters
 
 Ruff's `PLR0913` and `PLR0917` both complain about a long argument list, and a
@@ -241,6 +368,57 @@ The value arrives as a `Password`; call `.decrypt()` only where it is used.
 Typing it as `str` puts the secret in plain text in the task configuration and
 in the project export.
 
+An **empty secret field is still truthy**. A blank parameter arrives as a
+`Password` wrapping an empty value, and `Password` defines neither `__bool__`
+nor `__len__`, so the obvious guard never fires:
+
+```python
+if self.api_key:  # True even when the field was left blank
+    ...
+```
+
+A plugin whose behaviour depends on whether a secret was supplied takes the
+wrong branch, and the failure surfaces much later - as a library error deep
+inside whatever consumes the secret, or as a request sent with an empty
+credential. Ask the question against the decrypted value, through a helper that
+also accepts the plain `str` that a default value or a test supplies, and keep
+the answer rather than the plaintext:
+
+```python
+def _secret(value: Password | str) -> str:
+    return value if isinstance(value, str) else value.decrypt()
+
+self.signing = bool(_secret(private_key))  # keep the answer, not the secret
+```
+
+Tests hide this rather than catching it: a test passing a plain `str` exercises
+the naive guard correctly, so the mistake only appears against a deployment,
+where DataIntegration hands over a `Password`.
+
+## Validating an IRI the user types
+
+A knowledge graph IRI **is not necessarily a URL**. `urn:example:data` and
+`urn:uuid:...` are ordinary ways to name a graph, and the store imports into and
+queries one without complaint - so `validators.url()`, the obvious import,
+rejects a graph that works. The trap is quiet: the check looks right, and the
+resulting *Invalid value for parameter ...* never mentions that the scheme was
+what failed.
+
+`GraphParameterType` covers the case where the user picks a graph. Hand-written
+validation is for the ones they type - an ignore list, a target graph that does
+not exist yet, a class or property filter - and it has to accept a URN as well:
+
+```python
+URN = re.compile(r"^urn:[a-z0-9][a-z0-9-]{1,31}:\S+$", re.IGNORECASE)
+
+if not validators.url(iri) and not URN.match(iri):
+    raise ValueError(f"{iri} is neither a URL nor a URN.")
+```
+
+The namespace identifier is two to thirty-two characters starting with an
+alphanumeric one, and the namespace specific string must be non-empty
+(RFC 8141).
+
 ## Custom parameter types
 
 A `PluginParameter` without an explicit `param_type` gets one derived from the
@@ -304,6 +482,43 @@ class CollectionParameterType(StringParameterType):
 - Return a **stable order**. Sort at the end; do not deduplicate with `set()`
   after sorting, because that throws the ordering away again.
 
+### A choice dropdown is not shown in its declared order
+
+`ChoiceParameterType` does the very thing that last bullet warns against, so
+the `OrderedDict` it takes is **not** the order the user sees: `autocomplete()`
+sorts by label and then returns `list(set(result))`, and `Autocompletion` is a
+frozen dataclass, so the set reorders by hash bucket and discards the sort.
+Python randomizes string hashing per process, so the dropdown comes out
+differently after every restart of DataIntegration - which also means one run in
+three looks plausible enough to miss. Nothing local shows it: the `OrderedDict`
+is intact in the source and in the descriptors, and `task check` is green.
+
+So for a choice whose order carries meaning - priorities, log levels, sizes,
+compression levels, conflict policies - subclass it until
+<https://github.com/eccenca/cmem-plugin-base/issues/49> is released:
+
+```python
+class OrderedChoiceParameterType(ChoiceParameterType):
+    """A choice whose dropdown keeps the order the choices were declared in."""
+
+    def autocomplete(
+        self,
+        query_terms: list[str],
+        depend_on_parameter_values: list[Any],
+        context: PluginContext,
+    ) -> list[Autocompletion]:
+        """Return the choices matching all query terms, in their declared order."""
+        terms = [term.lower() for term in query_terms]
+        return [
+            Autocompletion(value=value, label=label)
+            for value, label in self.choice_list.items()
+            if all(term in label.lower() for term in terms)
+        ]
+```
+
+Numbering the labels does not rescue it - `(1)` to `(5)` only feeds the sort
+that is thrown away.
+
 ### The flags
 
 - `allow_only_autocompleted_values = True` makes the parameter a closed