cohorte 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -3,6 +3,35 @@
 Entries are shown by `/update-pipeline` ("What's new") after a core refresh. Keep them short,
 user-facing, most recent first. One `## <version> — <YYYY-MM-DD>` section per release.
 
+## 1.2.0 — 2026-07-29
+
+> **Opt-in anonymous telemetry, GDPR-first.** Nothing is sent unless you explicitly say yes.
+
+- `/init-pipeline` (and `/update-pipeline` on existing installs) ask ONE consent question, once per
+  machine, default **No** — both answers are recorded in `~/.claude/cohorte.config.yaml` §`telemetry`
+  so you're never re-asked.
+- When enabled, each pipeline phase fires a ~200-byte ping (fire-and-forget, 2s timeout, never
+  blocks): core version, OS, phase, duration, per-surface result counts, and a **hash** of the
+  feature id. Never sent: repo names, paths, code, spec content, IPs.
+- Withdraw anytime (`telemetry.enabled: false`); erase your history anytime (`/doctor` prints your
+  `install_id`; `DELETE /v1/install/<id>` on the collector drops it). Full spec: SCHEMA.md
+  §Telemetry; privacy summary in the README.
+- Ships a zero-dependency reference collector (`telemetry/collector.mjs` — NDJSON storage, strict
+  field allowlist, erasure endpoint, stores no IPs) to self-host.
+- `/doctor` reports telemetry consent state and flags incoherent configs (enabled without a
+  recorded consent).
+- Note: the shipped default `endpoint` is empty — telemetry stays dormant even for consenting
+  installs until a collector URL ships in the config template.
+
+## 1.1.1 — 2026-07-29
+
+- **Fix: pipeline metrics survive worktree teardown.** With `isolation.enabled` the lead session
+  runs inside the feature worktree, so metrics lines landed in the worktree's `.claude/` and were
+  deleted with it — defeating their purpose (cross-feature evidence for surface splits, dashboard
+  history). All phases now append to the **main checkout's** `.claude/pipeline-metrics.jsonl`,
+  resolved from anywhere via `git rev-parse --git-common-dir`; `/doctor` flags a stray metrics file
+  inside a worktree as a stale-core sign.
+
 ## 1.1.0 — 2026-07-29
 
 > **The token-economy release.** A full audit of the core (40 verified fixes) cuts the pipeline's

package/README.md

@@ -269,6 +269,16 @@ Rules that make it safe:
   their eventual reviews diff against reality.
 - `/doctor` check 6 shows the live slot table (feature ↔ worktree ↔ ports) when you lose track.
 
+## Privacy — opt-in telemetry
+
+Cohorte can send **anonymous** usage pings (core version, OS, phase name, duration, per-surface
+result counts, and a *hash* of the feature id — never repo names, paths, code, or IPs). It is
+**strictly opt-in**: `/init-pipeline` asks once per machine, the default is No, and both answers are
+recorded so you're never re-asked. Withdraw anytime (`telemetry.enabled: false` in
+`~/.claude/cohorte.config.yaml`); erase your history anytime (`/doctor` prints your `install_id`,
+the collector's `DELETE /v1/install/<id>` drops it). Full spec + GDPR details:
+`profile/SCHEMA.md` §Telemetry; reference collector in `telemetry/`.
+
 ## License
 
 [AGPL-3.0](LICENSE). Free to use, including commercially — but if you modify it and distribute it

package/core/commands/build.md

@@ -93,11 +93,18 @@ tree. For each surface in `surfaces`:
 
 When all return, flag any contract mismatch or failing test from the handoffs; otherwise print one
 status line per surface (`<key> · tests pass/fail · <n> TODOs`) — do not restate handoff content.
-Append **ONE line for the batch** to `.claude/pipeline-metrics.jsonl` (create it if absent; it must
-be gitignored), computing the elapsed time in the same Bash call
+Append **ONE line for the batch** to the **main checkout's** `.claude/pipeline-metrics.jsonl` —
+NOT the worktree's, which dies at teardown while metrics must accumulate across features. Resolve
+it from anywhere: `$(dirname "$(git rev-parse --git-common-dir)")/.claude/pipeline-metrics.jsonl`
+(in the main checkout this resolves to itself). Create it if absent; it must be gitignored.
+Compute the elapsed time in the same Bash call
 (`echo "{...\"seconds\":$(($(date +%s)-<start epoch from §2>)),...}" >> …`):
 `{"ts":"<ISO date>","feature":"$ARGUMENTS","phase":"build","seconds":<wall-clock>,"surfaces":{"<key>":"ok|error",…}}`
-— this is the evidence SCHEMA.md §Specialization asks for before splitting a surface.
+— this is the evidence SCHEMA.md §Specialization asks for before splitting a surface. In the same
+Bash call, chain the opt-in usage ping:
+`<core>/pipeline/scripts/telemetry-send.sh build "$ARGUMENTS" <seconds> "<ok,ok|error,…>" || true`
+(`<core>` = `~/.claude` global / `.claude` bundled) — a silent no-op unless the human explicitly
+consented (SCHEMA.md §Telemetry); never ask about consent here.
 Then tell the human: run `/smoke $ARGUMENTS` to exercise the feature end-to-end (or test by hand),
 then `/review $ARGUMENTS`. Do not run the app or migrations yourself here — `/smoke` is the
 sanctioned path for that. **Recommend a `/clear` now** — the spec, contract and diff are all on

package/core/commands/doctor.md

@@ -53,9 +53,18 @@ fix only with the human's go-ahead (or hand them the command).
    When ≥2 slots are live, print the parallel-feature table (feature · worktree · ports · db ·
    branch behind main by N commits) — a worktree far behind main means its next review will diff
    against stale code ⇒ suggest rebasing it.
-7. **Specs & metrics.** Every `specs/*.md` front-matter `status` is a valid stage; `shipped` specs
+7. **Telemetry** (consent hygiene — read `~/.claude/cohorte.config.yaml` §`telemetry`). Report the
+   status in one line: `disabled` / `enabled since <consent_date> · install_id <id> · endpoint <url>`
+   (the install_id is the human's GDPR erasure key — see SCHEMA.md §Telemetry). Flag ❌ any
+   incoherent state: `enabled: true` with no `install_id` or no `consent_date` (sending without
+   recorded consent — fix: set `enabled: false` until the consent question is re-run), or a
+   `telemetry:` block missing entirely on a current core (top up via `/update-pipeline`).
+8. **Specs & metrics.** Every `specs/*.md` front-matter `status` is a valid stage; `shipped` specs
    with a live worktree flagged (see 6). `.claude/pipeline-metrics.jsonl` and `specs/reports/` (the
-   `/review`·`/smoke` report buffer that lets a `/fix` survive a `/clear`) are gitignored.
+   `/review`·`/smoke` report buffer that lets a `/fix` survive a `/clear`) are gitignored. Metrics
+   belong to the **main checkout** — a `pipeline-metrics.jsonl` inside a live feature worktree is a
+   stale-core sign (its lines die at teardown) ⇒ suggest appending its lines to the main checkout's
+   file and deleting the stray.
 
 ## Report
 

package/core/commands/fix.md

@@ -60,7 +60,7 @@ When the agents return:
   re-reads each loop. Keep any round with ≥1 still-open `- [ ]` item fully expanded (§2's skip logic
   needs those checkboxes).
 - Print one status line per surface (`<key> · items fixed <n>/<m> · tests pass/fail`) — do not restate
-  handoff content — and append ONE metrics line for the batch to `.claude/pipeline-metrics.jsonl`
+  handoff content — and append ONE metrics line for the batch to `pipeline-metrics.jsonl`
   (see `/build` §4, `phase: "fix"`).
 - Tell the human: re-run `/smoke` if the failures were runtime ones, and `/review $ARGUMENTS` for the
   re-verdict — the re-review is what *verifies* the ticked items actually hold (a regression simply

package/core/commands/review.md

@@ -56,8 +56,8 @@ metrics line needs it.
 
 Merge the returned reports into **one** REVIEW REPORT (same template): findings concatenated and
 re-ordered by severity, counts summed, duplicates collapsed, verdict = the worst returned
-(`BLOCK` > `REVISE` > `SHIP`). Append ONE metrics line for the batch to `.claude/pipeline-metrics.jsonl`
-(gitignored): `{"ts":"<ISO>","feature":"$ARGUMENTS","phase":"review","seconds":<wall-clock>,"surfaces":{"<key>":"<verdict>:<finding count>",…}}`.
+(`BLOCK` > `REVISE` > `SHIP`). Append ONE metrics line for the batch to `pipeline-metrics.jsonl`
+(main-checkout path + rules in `/build` §4): `{"ts":"<ISO>","feature":"$ARGUMENTS","phase":"review","seconds":<wall-clock>,"surfaces":{"<key>":"<verdict>:<finding count>",…}}`.
 **Stage the full report to `specs/reports/$ARGUMENTS.md`** (overwrite) — a gitignored buffer so a
 `/fix` after a `/clear` can still read the findings; the `specs/reports/` subfolder is skipped by the
 non-recursive `specs/*.md` glob, so it's never mistaken for a spec (no phantom card, no bogus stage).

package/core/commands/smoke.md

@@ -33,7 +33,8 @@ human; that's expected.
 ## 3. Relay the verdict
 
 - Print the agent's return as-is (verdict + ❌ lines + report path) — it is already minimal.
-- Append ONE metrics line to `.claude/pipeline-metrics.jsonl` (see `/build` §4, `phase: "smoke"`).
+- Append ONE metrics line to `pipeline-metrics.jsonl` (main-checkout path + rules in `/build` §4,
+  `phase: "smoke"`).
 - **PASS** → tell the human to run `/review $ARGUMENTS`. **FAIL** → the failures are findings: feed
   them to `/fix $ARGUMENTS`, re-run `/smoke` after. Either way the report is on disk —
   **recommend a `/clear`** before the next command.

package/core/commands/update-pipeline.md

@@ -75,7 +75,10 @@ Two of the §Reconcile steps matter specifically here:
 
 - **Global config seed** (§Reconcile step 5): if `~/.claude/cohorte.config.yaml` is absent, seed it
   from the template so the kanban + shared-vault config has a home. Never clobber an existing filled
-  file. Report what was seeded.
+  file. Report what was seeded. If the existing file has NO `telemetry:` block with a `consent_date`
+  (pre-telemetry install), top up the block from the template and ask the ONE opt-in consent
+  question defined in `templates/steps/init-pipeline/02-interview-gaps.md` §Telemetry — record the
+  answer either way so it is never re-asked. Consent is strictly opt-in; "No" is the default.
 - **Kanban sync** (§Reconcile step 6): resolve this project's board from `kanban.boards[<PIPELINE
   name>]`. **Not linked** → offer to link/create a board (confirm the vault + `<folder>/Tasks.md`,
   write the `boards` entry, create the board file per §Kanban). **Linked** → verify the board file

package/core/templates/steps/init-pipeline/02-interview-gaps.md

@@ -39,3 +39,13 @@ Prefer sensible defaults from Phase 1 as the first (Recommended) option in each
 
 > The **kanban** link is user-scoped (it points at a personal vault, so it never goes in the committed
 > `PIPELINE.md`), but IS wired here because it is per-project — see Phase 4.
+
+- **Telemetry** (optional, machine-scoped — SKIP entirely if `~/.claude/cohorte.config.yaml` already
+  has a `telemetry:` block with a `consent_date`, i.e. the human already answered on this machine).
+  Ask ONE opt-in question, stating exactly: _"Share anonymous usage stats with the cohorte project?
+  Sent per pipeline phase: core version, OS, phase name, duration, per-surface result counts, and a
+  hash of the feature id — never repo names, paths, code, or IPs. Off by default; withdraw anytime
+  (`telemetry.enabled: false`); erase your history anytime (SCHEMA.md §Telemetry). Default: No."_
+  On **yes**: in the global config set `telemetry.enabled: true`, mint `install_id` (`uuidgen`,
+  lowercase), set `consent_date` (ISO date). On **no**: set `enabled: false` + `consent_date` (so
+  no future command re-asks). Never touch `endpoint` — it ships with the template.

package/install.ps1

@@ -144,6 +144,7 @@ try {
         Copy-Item (Join-Path $src 'profile\cohorte.config.template.yaml') (Join-Path $dest 'pipeline') -Force
         Copy-Item (Join-Path $src 'scripts\*.template')           (Join-Path $dest 'pipeline\scripts') -Force
         Copy-Item (Join-Path $src 'scripts\kanban-move.sh')       (Join-Path $dest 'pipeline\scripts') -Force
+        Copy-Item (Join-Path $src 'scripts\telemetry-send.sh')    (Join-Path $dest 'pipeline\scripts') -Force
         Copy-Item (Join-Path $src 'core\agents\implementer.template.md') (Join-Path $dest 'pipeline') -Force
         if (Test-Path (Join-Path $src 'CHANGELOG.md')) { Copy-Item (Join-Path $src 'CHANGELOG.md') (Join-Path $dest 'pipeline') -Force }
         [System.IO.File]::WriteAllText((Join-Path $dest 'pipeline\VERSION'), "$ver`n", [System.Text.UTF8Encoding]::new($false))

package/install.sh

@@ -86,7 +86,8 @@ copy_core() {
   cp "$src/profile/cohorte.config.template.yaml" "$dest/pipeline/"
   cp "$src"/scripts/*.template           "$dest/pipeline/scripts/"
   cp "$src/scripts/kanban-move.sh"       "$dest/pipeline/scripts/"
-  chmod +x "$dest/pipeline/scripts/kanban-move.sh" 2>/dev/null || true
+  cp "$src/scripts/telemetry-send.sh"    "$dest/pipeline/scripts/"
+  chmod +x "$dest/pipeline/scripts/kanban-move.sh" "$dest/pipeline/scripts/telemetry-send.sh" 2>/dev/null || true
   cp "$src/core/agents/implementer.template.md" "$dest/pipeline/"
   [ -f "$src/CHANGELOG.md" ] && cp "$src/CHANGELOG.md" "$dest/pipeline/"
   printf '%s\n' "$ver" > "$dest/pipeline/VERSION"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cohorte",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Portable, stack-agnostic multi-agent development pipeline for Claude Code — install the core, run /init-pipeline, and it adapts to your project's stack.",
   "bin": {
     "cohorte": "bin/cli.js"
@@ -16,6 +16,7 @@
     "dashboard/server",
     "dashboard/dist",
     "dashboard/README.md",
+    "telemetry",
     "install.sh",
     "install.ps1",
     "CHANGELOG.md"

package/profile/SCHEMA.md

@@ -155,10 +155,12 @@ the frozen contract as the only cross-surface channel**. So specialization means
 
 Coarse first, specialize on evidence: start with one `frontend` / `backend` surface each; split only a
 surface that's proven slow and cleanly separable. The evidence lives in
-`.claude/pipeline-metrics.jsonl` (gitignored) — one JSONL line per phase batch
+the **main checkout's** `.claude/pipeline-metrics.jsonl` (gitignored) — one JSONL line per phase batch
 (`ts`/`feature`/`phase`/`seconds`/`surfaces:{key: result}`), appended by `/build`, `/review`, `/fix`
-and `/smoke`. Read it before proposing a split: split the surface that actually dominates wall-clock,
-not the one that feels big.
+and `/smoke`. Always the main checkout, never the feature worktree (which dies at teardown while
+metrics must accumulate across features) — resolve from anywhere with
+`$(dirname "$(git rev-parse --git-common-dir)")/.claude/pipeline-metrics.jsonl`. Read it before
+proposing a split: split the surface that actually dominates wall-clock, not the one that feels big.
 
 ## Measuring cost — what's slow vs what's expensive
 
@@ -316,3 +318,39 @@ added vs. moved vs. already-correct.
 `<obsidian.vault_path>/<folder>/Tasks.md` with the `kanban-plugin: board` front-matter, one `## <heading>`
 per configured column in pipeline order, and the closing `%% kanban:settings %%` block
 (`{"kanban-plugin":"board","list-collapse":[false,…]}` with one `false` per column).
+
+## Telemetry — anonymous usage stats, strictly opt-in (GDPR-first)
+
+Cohorte can send the maintainers anonymous usage pings so the pipeline improves where it's actually
+slow. **Nothing is ever sent without explicit consent**: `/init-pipeline` (and `/update-pipeline` on
+pre-telemetry installs) ask ONE question, once per machine, default **No**, and record the answer in
+`~/.claude/cohorte.config.yaml` §`telemetry` (`enabled`, `install_id`, `consent_date`). The sender —
+`pipeline/scripts/telemetry-send.sh`, chained by each phase after its metrics line — is a silent
+no-op unless `enabled: true` AND `install_id` AND `endpoint` are all set, times out at 2s, and never
+fails the pipeline.
+
+**What one event contains** (strict allowlist, ~200 bytes):
+
+```json
+{"v":1,"install_id":"<random uuid>","ts":"<ISO>","core_version":"1.2.0","os":"Darwin",
+ "event":"phase","phase":"build","feature_hash":"<sha256[..12] of the feature id>",
+ "seconds":412,"results":"ok,ok"}
+```
+
+**What is NEVER sent:** repo/project names, file paths, code, spec content, prompts, emails,
+usernames, IP handling client-side. The feature id is hashed (12 hex chars) so cross-feature counts
+work without revealing what is being built.
+
+**GDPR rights, concretely:**
+
+- **Consent** — opt-in only, recorded with a date; "No" is also recorded so nothing re-asks.
+- **Withdrawal** — set `telemetry.enabled: false` in `~/.claude/cohorte.config.yaml`; effective on
+  the next phase, no restart.
+- **Erasure** — `/doctor` prints your `install_id`; send
+  `curl -X DELETE <endpoint-origin>/v1/install/<install_id>` and the collector drops every event
+  for that id (the reference collector in `telemetry/` implements this and stores no IPs).
+- **Access/portability** — events are keyed by your `install_id`; ask the operator for an export.
+
+**Collector contract** (implement your own, or deploy `telemetry/collector.mjs`):
+`POST /v1/events` (one JSON event, allowlisted fields) · `DELETE /v1/install/<id>` (erasure) ·
+`GET /healthz`. Operators must not retain IP-bearing access logs for the ingest vhost.

package/profile/cohorte.config.template.yaml

@@ -10,6 +10,20 @@
 
 enabled: true                 # cfg:enabled — master switch; false disables every capability below
 
+# ── telemetry (anonymous usage stats — OPT-IN, GDPR-first) ──────────────────
+# Strictly opt-in: nothing is ever sent unless YOU said yes to the consent question
+# (/init-pipeline or /update-pipeline ask once per machine; they record your answer here).
+# What is sent when enabled: core version, OS, phase name, wall-clock seconds, per-surface
+# result counts, and a SHA-256 HASH of the feature id — never repo names, paths, code, spec
+# content, emails, or IPs. Sent fire-and-forget (2s timeout, silent on failure) by
+# pipeline/scripts/telemetry-send.sh. Withdraw anytime: set enabled: false. Erase your history:
+# see SCHEMA.md §Telemetry (DELETE by install_id).
+telemetry:
+  enabled: false              # cfg:telemetry_enabled — true ONLY via explicit consent
+  install_id: ""              # cfg:telemetry_install_id — random UUID minted at consent; the erasure key
+  consent_date: ""            # cfg:telemetry_consent_date — ISO date the human said yes
+  endpoint: ""                # cfg:telemetry_endpoint — collector URL (maintainer default; empty = off even if enabled)
+
 # ── obsidian ──────────────────────────────────────────────────────────────────
 # Local vault used by the kanban mirror — defined here ONCE so no capability ever duplicates
 # the path. Absolute path to the folder you open in Obsidian.

package/scripts/telemetry-send.sh

@@ -0,0 +1,52 @@
+#!/bin/sh
+# telemetry-send.sh — fire-and-forget anonymous usage ping (SCHEMA.md §Telemetry).
+#
+#   telemetry-send.sh <phase> <feature_id> <seconds> [results]
+#     phase    build|review|fix|smoke
+#     feature  the feature id — NEVER sent raw; SHA-256-hashed to 12 hex chars
+#     seconds  batch wall-clock
+#     results  optional compact summary, e.g. "ok,ok" or "REVISE:3"
+#
+# GDPR posture (documented in SCHEMA.md §Telemetry):
+#   - STRICTLY opt-in: exits silently unless ~/.claude/cohorte.config.yaml has
+#     telemetry.enabled: true AND a non-empty endpoint AND an install_id
+#     (all three written only by the explicit consent flow).
+#   - Data minimization: no repo names, no paths, no code, no IP handling client-side.
+#   - Never blocks or fails the pipeline: 2s timeout, all errors swallowed, exit 0 always.
+set -u
+
+cfg="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/cohorte.config.yaml"
+[ -f "$cfg" ] || exit 0
+
+# read keys scoped to the `telemetry:` block only
+tval() {
+  awk -v key="$1" '
+    /^telemetry:/       { in_t=1; next }
+    /^[a-zA-Z]/         { in_t=0 }
+    in_t && $1 == key":" {
+      v=$2; gsub(/^"|"$|#.*/,"",v); gsub(/"/,"",v); print v; exit
+    }' "$cfg"
+}
+
+[ "$(tval enabled)" = "true" ] || exit 0
+endpoint="$(tval endpoint)";   [ -n "$endpoint" ]   || exit 0
+install_id="$(tval install_id)"; [ -n "$install_id" ] || exit 0
+
+phase="${1:-}"; feature="${2:-}"; seconds="${3:-0}"; results="${4:-}"
+[ -n "$phase" ] || exit 0
+
+if command -v shasum >/dev/null 2>&1; then
+  fhash=$(printf '%s' "$feature" | shasum -a 256 | cut -c1-12)
+else
+  fhash=$(printf '%s' "$feature" | sha256sum | cut -c1-12)
+fi
+ver=$(cat "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/pipeline/VERSION" 2>/dev/null | head -1)
+os=$(uname -s 2>/dev/null || echo unknown)
+ts=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+payload=$(printf '{"v":1,"install_id":"%s","ts":"%s","core_version":"%s","os":"%s","event":"phase","phase":"%s","feature_hash":"%s","seconds":%s,"results":"%s"}' \
+  "$install_id" "$ts" "$ver" "$os" "$phase" "$fhash" "${seconds:-0}" "$results")
+
+curl -s -m 2 -X POST -H 'content-type: application/json' \
+  -d "$payload" "$endpoint" >/dev/null 2>&1 || true
+exit 0

package/telemetry/README.md

@@ -0,0 +1,49 @@
+# cohorte telemetry collector (reference)
+
+Zero-dependency ingest endpoint for cohorte's **opt-in** anonymous usage pings
+(see the repo README §Privacy and `profile/SCHEMA.md` §Telemetry for what is —
+and is not — collected).
+
+## Deploy (any VPS, Node ≥ 18)
+
+```sh
+TELEMETRY_DATA=/var/lib/cohorte-telemetry/events.ndjson \
+TELEMETRY_PORT=8787 node collector.mjs
+```
+
+Put it behind HTTPS (Caddy example):
+
+```
+telemetry.yourdomain.tld {
+    reverse_proxy 127.0.0.1:8787
+    log { output discard }   # GDPR: do NOT keep access logs with IPs for this vhost
+}
+```
+
+Then set the public URL as the `endpoint:` default in
+`profile/cohorte.config.template.yaml` (anchor `cfg:telemetry_endpoint`) and release —
+consenting installs start sending to it.
+
+## API
+
+| Method | Path | Purpose |
+|---|---|---|
+| `POST` | `/v1/events` | Ingest one event (strict field allowlist, 4 KB max) |
+| `DELETE` | `/v1/install/<install_id>` | **Right to erasure** — drops every event for that id |
+| `GET` | `/healthz` | Liveness |
+
+Storage is an append-only NDJSON file — point your dashboard (or a cron that loads
+into SQLite/Postgres) at it. One JSON object per line:
+
+```json
+{"v":1,"install_id":"…","ts":"…","core_version":"1.2.0","os":"Darwin","event":"phase","phase":"build","feature_hash":"a1b2c3d4e5f6","seconds":412,"results":"ok,ok","received_at":"…"}
+```
+
+## GDPR checklist (operator side)
+
+- [x] Opt-in only — the client never sends without recorded consent
+- [x] No IPs stored (collector ignores them; disable proxy access logs)
+- [x] Data minimization — hashed feature ids, no repo names/paths/code
+- [x] Erasure — `DELETE /v1/install/<id>`; the user finds their id via `/doctor`
+- [x] Withdrawal — `telemetry.enabled: false` in `~/.claude/cohorte.config.yaml`
+- [ ] Your privacy notice — link the repo README §Privacy from wherever you present cohorte

package/telemetry/collector.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// Reference telemetry collector for cohorte — zero-dependency, GDPR-first.
+// Deploy on any VPS behind HTTPS (Caddy/nginx). Storage: NDJSON append-only file,
+// one event per line — read it from your own dashboard however you like.
+//
+//   TELEMETRY_DATA=/var/lib/cohorte-telemetry/events.ndjson \
+//   TELEMETRY_PORT=8787 node collector.mjs
+//
+// GDPR notes:
+//   - IPs are NEVER stored (this process doesn't read them; make sure your reverse
+//     proxy's access log is disabled or anonymized for this vhost).
+//   - DELETE /v1/install/<install_id> erases every event for that id (right to erasure —
+//     the install_id printed by /doctor is the user's erasure key).
+//   - Events are validated against a strict allowlist of fields; anything else is dropped.
+import { createServer } from "node:http";
+import { appendFileSync, existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+const DATA = process.env.TELEMETRY_DATA || "./events.ndjson";
+const PORT = Number(process.env.TELEMETRY_PORT || 8787);
+const MAX_BODY = 4096;
+
+mkdirSync(dirname(DATA), { recursive: true });
+
+const FIELDS = ["v", "install_id", "ts", "core_version", "os", "event",
+  "phase", "feature_hash", "seconds", "results"];
+const ID_RE = /^[A-Za-z0-9-]{8,64}$/;
+
+function sanitize(raw) {
+  const e = {};
+  for (const k of FIELDS) if (k in raw) e[k] = raw[k];
+  if (e.v !== 1) return null;
+  if (typeof e.install_id !== "string" || !ID_RE.test(e.install_id)) return null;
+  if (typeof e.event !== "string" || e.event.length > 32) return null;
+  for (const k of ["ts", "core_version", "os", "phase", "feature_hash", "results"])
+    if (k in e && (typeof e[k] !== "string" || e[k].length > 64)) return null;
+  if ("seconds" in e && typeof e.seconds !== "number") return null;
+  e.received_at = new Date().toISOString();
+  return e;
+}
+
+const server = createServer((req, res) => {
+  const done = (code, body) => { res.writeHead(code, { "content-type": "application/json" }); res.end(JSON.stringify(body)); };
+
+  if (req.method === "GET" && req.url === "/healthz") return done(200, { ok: true });
+
+  if (req.method === "POST" && req.url === "/v1/events") {
+    let body = "";
+    req.on("data", (c) => { body += c; if (body.length > MAX_BODY) req.destroy(); });
+    req.on("end", () => {
+      try {
+        const e = sanitize(JSON.parse(body));
+        if (!e) return done(400, { error: "invalid event" });
+        appendFileSync(DATA, JSON.stringify(e) + "\n");
+        done(204, {});
+      } catch { done(400, { error: "bad json" }); }
+    });
+    return;
+  }
+
+  // Right to erasure: drop every event carrying this install_id.
+  const del = req.url?.match(/^\/v1\/install\/([A-Za-z0-9-]{8,64})$/);
+  if (req.method === "DELETE" && del) {
+    const id = del[1];
+    let kept = [], dropped = 0;
+    if (existsSync(DATA))
+      for (const line of readFileSync(DATA, "utf8").split("\n")) {
+        if (!line.trim()) continue;
+        if (line.includes(`"install_id":"${id}"`)) { dropped++; continue; }
+        kept.push(line);
+      }
+    writeFileSync(DATA, kept.length ? kept.join("\n") + "\n" : "");
+    return done(200, { erased: dropped });
+  }
+
+  done(404, { error: "not found" });
+});
+
+server.listen(PORT, () => console.log(`cohorte telemetry collector on :${PORT} → ${DATA}`));