feat: bug-report collector pseudonymises identities in two stages, opt-in via --pseudonymise (#158)

Files changed:
- .gitea/workflows/ci.yml
- CHANGES.md
- INSTALL.md
- VERSION
- instructions/bug-report.md
- reports/CONTRACT.md
- tools/README.md
- tools/bugreport.py
- tools/chemenu/tests/test_bugreport.py

instructions/bug-report.md

@@ -53,6 +53,26 @@ out** unless `--titles` is given: paths under `kb/` and `raw/` are replaced by t
 flags. A title that stands as bare prose is not found - which is why the trace, the chronology and the
 transcripts are marked instead.
 
+**Pseudonymisation is optional** (`--pseudonymise`) and runs in two stages. The bundle then keeps the
+*shape* of every name - length per word, spaces, hyphens, character classes, separators, depth of a
+path - because that is what an installation failure turns on, and replaces the name itself.
+
+- **Stage 1 is mechanical.** The script reads what the machine knows about its user - user name,
+  host, home and repository path, git identity, remote URLs - and replaces each identity in every
+  text file by a placeholder. The same word always gets the same placeholder, in every file and in
+  JSON-escaped form too. The stack's own public origin and system folder names stay readable.
+- **Stage 2 is a model's judgement, applied mechanically.** Names the script cannot know - people,
+  companies, customers, internal hosts, projects - are named by you as candidates in a file; the
+  script applies them with the same machinery. You replace nothing in the bundle yourself.
+- **Three local files** sit beside the bundle directory, never inside it and never in the zip:
+  `bugreport-<stamp>.pseudonyms.json` (the mapping), `bugreport-<stamp>.review.txt` (what stage 1
+  left behind, for you to read) and the candidate file you write. All three contain originals.
+- **A residual uncertainty remains and is always named:** stage 2 can miss a name, above all in the
+  free text of a large trace or transcript that you did not read in full.
+
+The model of the harness reads the bundle for stage 2 - the same place that already sees this
+session. The bundle does not leave that place because of it.
+
 ## When to run
 
 - Setup or an upgrade failed and the user wants to report it.
@@ -66,6 +86,10 @@ transcripts are marked instead.
    remotes, and it is not sent anywhere. Ask whether the session trace, page titles and transcripts
    may go in. The defaults are: trace in, titles out, no transcripts.
 
+   Ask which channel the bundle will take, and recommend pseudonymisation for every channel except a
+   direct handover to the maintainer over a secure channel: a tracker issue, an email or a chat is
+   not one. The default is off; say so, and that it costs one more step.
+
 2. **Write the chronology** to a file under `reports/` (which is gitignored) from the
    [template](#chronology-template) below. Facts only - no diagnosis. If the session's own history is
    too long to reconstruct, say what is missing instead of filling the gap.
@@ -78,17 +102,35 @@ transcripts are marked instead.
 
    Add `--no-trace` if the user declined the trace, `--titles` if titles may stay,
    `--transcript <file>` (repeatable) for a transcript the user pointed at, `--session <id>` to take a
-   trace other than the caller's. `python3` may be `python` or `py -3` on Windows. If no Python starts
+   trace other than the caller's, `--pseudonymise` if the user chose it (stage 1). `python3` may be `python` or `py -3` on Windows. If no Python starts
    at all, that is the report: give the user the exact error text, verbatim.
 
-4. **Do not imitate the collector's session id.** It runs its counting `wikitool` calls under
+4. **Stage 2, only if the bundle was pseudonymised.** Read, in the bundle: `CHRONOLOGY.md` and
+   `MANIFEST.md` completely; the review list `reports/bugreport-<stamp>.review.txt` completely; the
+   trace and each transcript completely only if the file is under 100 KB, otherwise only what the
+   review list points to. Name what is still left of a person, company, customer, internal host or
+   domain, or project - one per line in `reports/candidates.txt`; `#` starts a comment. Then run:
+
+   ```bash
+   python3 tools/bugreport.py --bundle reports/bugreport-<stamp> --candidates reports/candidates.txt
+   ```
+
+   The script applies the candidates with the machinery of stage 1, reports which it did not apply
+   (too short, system vocabulary, not found) and packs the zip again. **Never replace anything in
+   the bundle yourself.** The run can be repeated with further candidates. It refuses, with exit 1 and
+   an unchanged bundle, when the mapping beside the bundle is gone.
+
+5. **Do not imitate the collector's session id.** It runs its counting `wikitool` calls under
    `WIKITOOL_SESSION_ID=bugreport-<stamp>` itself; do not export that variable, or any `bugreport-*`
    one, in the session. The exception it gets in [gates.md](gates.md) § "Taking a new session id"
    belongs to the script alone.
 
-5. **Report the result.** Quote the bundle path, the archive path and the privacy notice the script
+6. **Report the result.** Quote the bundle path, the archive path and the privacy notice the script
    prints, name the gaps in `MANIFEST.md`, and tell the user to read the bundle before sharing it.
-   Then stop: the channel - a tracker issue, an email, a chat - is the user's choice, and the agent
+   After stage 2, name the residual uncertainty in words of your own: stage 2 is a model's judgement
+   and can have missed names, above all in the free text of a trace or transcript over 100 KB.
+   Say that the mapping, the review list and the candidate file hold originals and stay on this
+   machine, and that the mapping may be deleted after the last stage 2 run. Then stop: the channel - a tracker issue, an email, a chat - is the user's choice, and the agent
    never uploads the bundle.
 
 ## Chronology template
@@ -121,6 +163,11 @@ Facts only: no page content, no guessed cause, no advice.
 
 ## Decision points
 
+- **The mapping is gone before stage 2?** Stage 2 refuses: it needs the salt stage 1 used, or it would
+  replace a word differently from the path it already replaced. Collect the report again with
+  `--pseudonymise`.
+- **The user wants a name added after stage 2?** Run stage 2 again with a candidate file holding only
+  that line. The same run also works when the human spots a name while reading the bundle.
 - **The user declines the trace?** Run with `--no-trace`. The manifest records the exclusion.
 - **The failure can be reproduced, and there is no trace?** A distributed instance records none by
   default. Offer to repeat the failing step in one new shell with `WIKI_TRACE=1` set for that