session-orchestrator 3.16.0 → 3.19.0

package/docs/session-config-template.md

@@ -75,6 +75,16 @@ stale-issue-days: 30                   # issue-age threshold for triage flag
 
 Read by: `skills/session-start/SKILL.md`, `skills/ecosystem-health/SKILL.md`, `skills/gitlab-ops/SKILL.md`.
 
+## Auto-Skill Dispatch
+
+```yaml
+auto-skill-dispatch: false             # opt-in; phrase-match meta-skill — see skills/using-orchestrator/SKILL.md
+```
+
+Top-level scalar (not nested). When `true`, entry-point skills invoke `skills/using-orchestrator/SKILL.md` once before their own Phase 1 to detect implicit slash-command intent in the user's first message (bilingual EN/DE phrase map, confidence-scored, AUQ-disambiguated on close ties). Default `false` — zero behavior change until opted in.
+
+Read by: `skills/using-orchestrator/SKILL.md`, `skills/_shared/bootstrap-gate.md`.
+
 ## Quality Gates
 
 ```yaml
@@ -91,7 +101,7 @@ Read by: `skills/quality-gates/SKILL.md`, `skills/session-end/SKILL.md`. The thr
 ## Discovery
 
 ```yaml
-discovery-on-close: auto               # session-type aware: housekeeping=false, feature/deep=true (#264)
+discovery-on-close: auto               # auto = true for every session type (was housekeeping=false until 2026-07-29)
 discovery-probes: [all]                # all | code | infra | ui | arch | session | audit | vault | feature
 discovery-exclude-paths: []            # globs (e.g. "vendor/**", "dist/**")
 discovery-severity-threshold: low      # critical | high | medium | low
@@ -101,6 +111,17 @@ discovery-parallelism: 5               # 1..16 probe agents in parallel
 
 Read by: `skills/discovery/SKILL.md` and the probe modules under `skills/discovery/probes-*.md`.
 
+## Issue Budget
+
+```yaml
+issue-budget:
+  max-per-session: 12                  # non-exempt issues one session may create (0 = block all)
+  mode: strict                         # strict | warn | off
+  overflow: collect-issue              # collect-issue | vault-note
+```
+
+Quantity cap, not a quality filter — `discovery-*-threshold` above cannot bound creation volume. `priority::critical`, the carryover class and `broken-window` issues are exempt. Read by: `hooks/pre-bash-issue-budget.mjs`, `scripts/lib/spiral-carryover.mjs`, `skills/session-end/SKILL.md` Phase 5 Step 3b.
+
 ## Persistence & Safety
 
 ```yaml
@@ -115,6 +136,12 @@ enforcement-gates:
   path-guard: true
   command-guard: true
   post-edit-validate: true
+  bash-write-verify: true              # PostToolUse/Bash working-tree diff, warn-only (#915)
+  # bash-write-guard: true             # ⚠ INVERTED DEFAULT — this is the ONE gate that is
+                                       #   OFF when the key is absent. Every other key above
+                                       #   means "enabled unless set to false"; this one runs
+                                       #   only on a literal `true`. Leaving it out does NOT
+                                       #   leave Bash writes guarded (#800/#915).
 allow-destructive-ops: false           # disables destructive-command guard when true
 reasoning-output: false                # opt-in STATE:/PLAN: agent transparency markers
 grounding-check: true                  # session-end Phase 1.1a planned-vs-touched diff
@@ -124,7 +151,9 @@ max-turns: auto                        # housekeeping=8, feature=15, deep=25
 auto-commit-per-wave: false            # opt-in: commit after each wave's Quality-Lite PASS (default false; V3.6 plumbing)
 ```
 
-Read by: `skills/session-start/SKILL.md`, `skills/session-end/SKILL.md`, `hooks/pre-edit-scope.mjs`, `hooks/pre-bash-destructive-guard.mjs`, `hooks/pre-bash-enforce-commands.mjs`, `hooks/post-edit-validate.mjs`.
+Read by: `skills/session-start/SKILL.md`, `skills/session-end/SKILL.md`, `hooks/pre-edit-scope.mjs`, `hooks/pre-bash-destructive-guard.mjs`, `hooks/pre-bash-enforce-commands.mjs`, `hooks/post-edit-validate.mjs`, `hooks/post-bash-write-verify.mjs`.
+
+> **The `bash-write-guard` gate is the single inverted default in this block.** `hooks/enforce-commands.mjs` runs it only when `gates['bash-write-guard'] === true` is set literally; a missing key means the gate is OFF, unlike `path-guard`/`command-guard`/`post-edit-validate`/`bash-write-verify`, where a missing key means ON. Assuming otherwise is exactly the gap #915 was filed for — `hooks/enforce-scope.mjs` gates only `Edit`/`Write`/`MultiEdit`, so with `bash-write-guard` off nothing pre-checks the path of a `echo x > out-of-scope.mjs`. Full rationale (including the measured false-positive rate that justifies keeping it opt-in) in `docs/session-config-reference.md` § enforcement-gates.
 
 ## Resource Awareness (env-aware)
 
@@ -284,7 +313,7 @@ Read by: `scripts/lib/config/handover-gate.mjs`, `skills/session-end/SKILL.md` P
 
 ## Broken-Window Budget
 
-Opt-in gate in `/close` (session-end Phase 2.6). When enabled, it aggregates THIS session's "knowingly-broken shipments" (echo-stubs shipped under `enforcement: warn`, Phase 2.3/2.5 "Override and close" choices, MED/LOW findings routed to "Unresolved Review Findings", wave-level overridden findings) and files ONE hard-terminated closure issue per item (labels `broken-window` + `priority:high`, hard due-date). Non-blocking and idempotent (issue #730, Epic H / H5).
+Opt-in gate in `/close` (session-end Phase 2.6). When enabled, it aggregates THIS session's "knowingly-broken shipments" (echo-stubs shipped under `enforcement: warn`, Phase 2.3/2.5 "Override and close" choices, MED/LOW findings routed to "Unresolved Review Findings", wave-level overridden findings) and files ONE hard-terminated closure issue per item (labels `broken-window` + `priority::high`, hard due-date). Non-blocking and idempotent (issue #730, Epic H / H5).
 
 ```yaml
 broken-window-budget:
@@ -466,6 +495,21 @@ docs-staleness:
   mode: warn                           # strict | warn | off
   thresholds:
     living: 90                         # days — single tier; severity escalates at 1×/2×/3× threshold
+moc-staleness:
+  # Parser gotcha: this key line must carry NO inline comment.
+  enabled: false                       # opt-in — <vault>/08-topics/*-moc.md staleness banner (session-start Phase 4)
+  thresholds:
+    moc: 90                            # days — frontmatter `updated:` threshold; missing/unparseable is EXCLUDED, not reported
+  mode: warn                           # warn | off
+context-coverage:
+  # Parser gotcha: this key line must carry NO inline comment.
+  enabled: false                       # opt-in — registered 01-projects/ folders lacking context.md AND _passive.md
+  mode: warn                           # warn | off
+worktree-orphans:
+  # Parser gotcha: this key line must carry NO inline comment.
+  enabled: false                       # opt-in — session-end Phase 4b sweep; CANDIDATES ONLY, never auto-deletes (PSA-003)
+  base-branch: main                    # validated — a leading-dash value is rejected and falls back to main
+  mode: warn                           # warn | off
 ```
 
 Read by: `skills/discovery/probes/docs-staleness.mjs`, `scripts/lib/config/docs-staleness.mjs`.
@@ -665,6 +709,8 @@ enforcement-gates:
   path-guard: true
   command-guard: true
   post-edit-validate: true
+  bash-write-verify: true              # PostToolUse/Bash working-tree diff, warn-only (#915)
+  # bash-write-guard: true             # ⚠ INVERTED DEFAULT: absent = OFF (opposite of the keys above)
 allow-destructive-ops: false
 reasoning-output: false
 grounding-check: true
@@ -820,6 +866,18 @@ docs-staleness:
   mode: warn
   thresholds:
     living: 90
+moc-staleness:
+  enabled: false
+  thresholds:
+    moc: 90
+  mode: warn
+context-coverage:
+  enabled: false
+  mode: warn
+worktree-orphans:
+  enabled: false
+  base-branch: main
+  mode: warn
 
 # CLAUDE.md drift check
 drift-check:
@@ -867,6 +925,11 @@ loop-guard:
 instruction-budget:
   enabled: true            # always-on directive-budget banner; off-by-config silences it
   ceiling: 480             # structural-directive ceiling (baseline ~457; ratchet guards growth)
+  byte-ceiling: 114000     # byte ceiling for the SAME corpus (baseline ~108589, +5% headroom —
+                           # deliberately the same relative slack the directive ceiling carries,
+                           # so neither axis is accidentally the stricter one). Either axis alone
+                           # puts the banner over budget: a 9 KB prose rule with three bullets is
+                           # invisible to the directive count but costs real payload (#931a).
   mode: warn               # warn (surface banner) | off (silent no-op)
 
 # Config-protection guard (ecc-analysis / #622)

package/docs/telemetry/telemetry-claims.md

@@ -0,0 +1,204 @@
+# Telemetry Claims — Provenance & Methodology
+
+> **Not the opt-in usage-telemetry client.** This document explains the
+> methodology behind the maintainer's **local, private** metrics aggregates
+> (`.orchestrator/metrics/*.jsonl`, gitignored by design) used in marketing
+> copy such as "645 orchestrated sessions." It is a separate data flow from
+> the plugin's optional, strictly opt-in anonymous usage-telemetry client —
+> see [docs/telemetry.md](../telemetry.md) for what that client collects,
+> its kill switches, and where the data goes.
+
+> Cross-repo aggregate over the maintainer's private session corpus as of 2026-06.
+> Not independently auditable: the per-session records this aggregate is computed
+> from are gitignored (privacy by default). This is a **snapshot, not a live
+> counter** — re-running the math on a later date yields different numbers.
+
+_As-of: 2026-06 (maintainer-reported)_
+
+This document explains the telemetry figures used in public-facing material (e.g.
+agenticbuilders.at) so the claim is verifiable in *method* even though the
+absolute owner numbers cannot be reproduced from any public artifact. No marketing
+copy lives here — only what each number means, where it comes from, and how it is
+derived.
+
+---
+
+## Headline claim
+
+> **645 orchestrated sessions · 1,680 documented learnings · 7,700+ agent runs
+> (98.8% cleanly completed) · up to 34 parallel agents · 17 repos · as of 2026-06**
+
+Every figure above is a **cross-repo aggregate** computed over the local,
+**gitignored** JSONL metric files of several of the maintainer's private repos:
+
+```
+.orchestrator/metrics/sessions.jsonl
+.orchestrator/metrics/learnings.jsonl
+.orchestrator/metrics/subagents.jsonl
+.orchestrator/metrics/events.jsonl
+```
+
+These files are listed in `.gitignore` by design (privacy by default). No public
+commit, release, or CI artifact contains them, so the headline totals are
+**maintainer-reported** and not independently auditable. What *is* reproducible is
+the measurement recipe — see [Reproduce it yourself](#reproduce-it-yourself).
+
+---
+
+## Claims table
+
+| Claim | Source file | What one record means | How aggregated | As-of |
+| --- | --- | --- | --- | --- |
+| 645 orchestrated sessions | `sessions.jsonl` | 1 line = 1 complete `/session` -> `/close` cycle | `wc -l` summed across all contributing repos | 2026-06 |
+| 1,680 documented learnings | `learnings.jsonl` | 1 line = 1 extracted, confidence-scored learning (written by `/evolve`) | `wc -l` summed across repos | 2026-06 |
+| 7,700+ agent runs | `subagents.jsonl` | 1 dispatched subagent run (see note below on `start`/`stop` pairing) | `wc -l` (or `start`-event count) summed across repos | 2026-06 |
+| 98.8% cleanly completed | `subagents.jsonl` (+ `events.jsonl`) | completion status of a dispatched run | completed runs / total dispatched runs — *maintainer-reported, see methodology* | 2026-06 |
+| up to 34 parallel agents | `subagents.jsonl` / `events.jsonl` | peak count of agents dispatched concurrently | max over time-windowed `start`/`stop` overlap | 2026-06 |
+| 17 repos | n/a (corpus scope) | a repo that contributed at least one `sessions.jsonl` line | count of contributing repos | 2026-06 |
+
+---
+
+## In-repo test suite — the "10,000+ tests" badge
+
+Distinct from the private-corpus figures above, the README **Tests** badge and the
+"10,000+ vitest tests run on every commit" line count **this repository's own test
+suite** — a **public, CI-verifiable** number, not a maintainer-reported aggregate.
+
+| Claim | What it counts | How measured | As-of |
+| --- | --- | --- | --- |
+| 10,000+ vitest tests | executed test cases across `tests/**/*.test.mjs` | `npm test` prints the exact runtime total; the static floor is countable without running the suite (below) | 2026-06 |
+
+Both numbers reproduce in a fresh checkout:
+
+```bash
+find tests -name '*.test.mjs' | wc -l                    # test files            -> 475
+grep -rohE '\b(it|test)\(' tests | wc -l                 # static test defs      -> ~9,871
+grep -rohE '\b(it|test|describe)\.each\b' tests | wc -l   # parameterized blocks  -> 93
+```
+
+The static `it(` / `test(` count (~9,871 across 475 files) is a **floor**: the 93
+`it.each` / `test.each` parameterized blocks each expand to multiple executed cases
+at runtime, so the **case count vitest reports on `npm test` is 10,000+**. Unlike the
+private-corpus figures above, this one is fully auditable — run `npm test` in this
+checkout and read vitest's summary line.
+
+## Methodology
+
+### Session / learning / agent-run counts
+
+Each total is the sum of `wc -l` over the corresponding JSONL file across every
+contributing repo:
+
+```bash
+# per repo, then summed by hand across the corpus
+wc -l .orchestrator/metrics/sessions.jsonl    # -> orchestrated sessions
+wc -l .orchestrator/metrics/learnings.jsonl   # -> documented learnings
+wc -l .orchestrator/metrics/subagents.jsonl   # -> agent-run records
+```
+
+The JSONL format is append-only (one JSON object per line), so a line count is a
+faithful event count. There is no de-duplication step across repos — each repo
+contributes its own disjoint slice.
+
+### "Up to 34 parallel agents"
+
+This is the **peak** number of agents dispatched at the same time, not an average.
+It is read off the time windows in `subagents.jsonl` / `events.jsonl`: each agent
+run has a `start` and a `stop` record with timestamps; the peak is the maximum
+number of runs whose `[start, stop]` intervals overlap at any instant. Structurally
+this equals `agents-per-wave x concurrently-running waves` at the busiest moment of
+the busiest session. The session config governing fan-out (`agents-per-wave`,
+`waves`) lives in each repo's `CLAUDE.md` Session Config block.
+
+> **Note (2026-07-03, refs #724):** the small-batch dispatch default (3–4 `Agent()`
+> calls per message, `wave-loop.md § Dispatch Agents`) structurally lowers future
+> instantaneous peaks — agents within a wave now start in staggered batches rather
+> than a single simultaneous fan-out, so the overlapping-interval peak trends below
+> the historical `agents-per-wave × waves` ceiling this figure was read off.
+
+### "98.8% cleanly completed"
+
+Defined as **runs that completed cleanly / all dispatched runs**, where a clean
+completion is a run that reached its terminal `stop` with a `complete` status (as
+opposed to `spiral`- or `failed`-classified outcomes the orchestrator records for
+runs that loop or error out). This ratio is **maintainer-reported**: it is computed
+over the owner's full private corpus, and the exact per-run status classification
+is not present in every repo's local slice.
+
+> **Caveat (verified against this repo's own slice):** in *this* public repo,
+> `subagents.jsonl` records only `event: "start"` / `event: "stop"` markers (no
+> per-run `status` field). The completion percentage therefore cannot be
+> re-derived from this repo alone; it is an attribute of the owner's larger
+> private corpus and is labelled maintainer-reported accordingly.
+
+---
+
+## Reproduce it yourself
+
+Skeptics cannot reproduce the *owner's absolute totals* (the source records are
+gitignored), but the **measurement pattern is fully reproducible** on your own
+machine. After running N of your own sessions:
+
+```bash
+wc -l .orchestrator/metrics/sessions.jsonl    # your orchestrated sessions
+wc -l .orchestrator/metrics/learnings.jsonl   # your documented learnings
+wc -l .orchestrator/metrics/subagents.jsonl   # your agent runs
+```
+
+Each command returns *your* numbers using the exact same definitions in the claims
+table above. As a worked example, this very repo's local slice at the time of
+writing reports:
+
+```
+  29 .orchestrator/metrics/sessions.jsonl
+  97 .orchestrator/metrics/learnings.jsonl
+1796 .orchestrator/metrics/subagents.jsonl
+```
+
+(maintainer-reported, verifiable by running the commands above in this checkout).
+The point is that the *method* is transparent and runs identically everywhere; only
+the maintainer's aggregate magnitude stays private.
+
+---
+
+## Framing & limits
+
+These figures are the **maintainer's own telemetry**. They are **not** Anthropic
+benchmarks, not Anthropic-published limits, and not a claim about what Claude or any
+model "can do" in general. They describe how this orchestrator was operated across
+one maintainer's private repos.
+
+In particular, **Anthropic does not document a hard parallel-agent limit**; the
+"up to 34 parallel agents" figure is an observed peak of *this* tooling's fan-out,
+not a platform ceiling. For readers who want vendor-side context on multi-agent
+cost and design (cited only for orientation, not as a source for the numbers
+above):
+
+- Multi-agent token cost — "agents typically use about 4x more tokens than chat
+  interactions, and multi-agent systems use about 15x more tokens." Anthropic,
+  *How we built our multi-agent research system* (2025-06-13).
+  <https://www.anthropic.com/engineering/built-multi-agent-research-system>
+- The orchestrator-workers pattern this tool implements is described in Anthropic,
+  *Building effective agents* (2024-12-19).
+  <https://www.anthropic.com/engineering/building-effective-agents>
+
+No other Anthropic claims are made or implied here.
+
+---
+
+## Privacy
+
+What is **never published** from the source corpus:
+
+- Absolute filesystem paths
+- Hostnames (`.local` / `.lan` / `.internal`, etc.)
+- Repository names and VCS URLs (org/repo paths)
+- Prompts, session contents, or any free-form text
+- Emails, git-author identities, tokens, IP addresses
+
+Only aggregate counts and definitions leave the private corpus. This mirrors the
+anonymization pattern already enforced for shared learnings by
+`scripts/export-hw-learnings.mjs` (see also hardware-patterns; vault-archived; regenerated via `npm run share:hw-learnings`),
+which strips paths, IPs, VCS URLs, hostnames, emails, git authors, and token-shaped
+strings, and exports only structured fields — never free-form user text. The same
+"counts out, records stay home" principle applies to every figure in this document.

package/docs/telemetry.md

@@ -0,0 +1,158 @@
+# Telemetry
+
+Session Orchestrator ships an **optional, strictly opt-in** anonymous
+usage-telemetry client. This page is the transparency contract: exactly what
+is collected, what is never collected, how consent works, every kill switch,
+where the data goes, and how long it is kept. Nothing here is aspirational —
+it is the locked v1 schema and consent precedence this plugin implements.
+
+## TL;DR
+
+- **Off by default.** Nothing is sent until you explicitly consent.
+- **One prompt, ever.** An interactive session asks once, at most; the
+  answer is saved locally and never asked again (until you reset it).
+- **Trivial to turn off**, at any time, with an environment variable or a
+  one-line CLI command — no restart, no config-file archaeology.
+- **No CI/headless sends, ever.** Non-interactive sessions never prompt and
+  never send, regardless of prior consent state.
+- **Fully open source.** The client code and the ingest-server code both
+  live in this repository — nothing is a black box.
+- **Not the same thing as the local metrics used in marketing claims.** See
+  [Relationship to `telemetry-claims.md`](#relationship-to-telemetry-claimsmd)
+  below.
+
+## What we collect
+
+When telemetry is enabled and a batch is flushed, the payload is built from
+a strict field whitelist — nothing outside this list is ever included, and a
+projection unit test enforces the drop of any non-whitelisted input field.
+
+| Field | Meaning |
+|---|---|
+| `record_kind` | Always `"usage-ping"` for this record type. |
+| `schema_version` | Currently `1`. Additive-only evolution within a version — see [Schema evolution](#schema-evolution). |
+| `anon_id` | A random UUID, not derived from any machine identifier. Rotates every 90 days; the old ID is discarded, not linked to the new one. |
+| `sent_at` | Timestamp of the flush. |
+| `plugin_version` | The installed plugin's semver. |
+| `platform` | One of `claude`, `codex`, `cursor`, `pi`, `other`. |
+| `os` | Operating system family (e.g. `darwin`, `linux`, `win32`). |
+| `arch` | CPU architecture (e.g. `arm64`, `x64`). |
+| `node_major` | Major Node.js version in use. |
+| `ci` | Boolean — whether the run was detected as a CI environment. |
+| `fleet` | Boolean — whether this send came from an operator's own fleet-mode host (`owner.yaml` opt-in), as opposed to an external install. |
+| `session_type` | One of `housekeeping`, `feature`, `deep`, `other`. |
+| `duration_bucket` | One of `<15m`, `15-60m`, `1-3h`, `>3h` — a coarse bucket, never an exact duration. |
+| `skills[]` | Names of invoked skills, filtered against the shipped plugin roster — any name not in that roster becomes `"other"`. |
+| `commands[]` | Same filtering rule as `skills[]`. |
+
+## What we never collect
+
+This list is a hard invariant, not a deferral:
+
+- No repository names, no file paths, no git remotes.
+- No prompts, no session transcripts, no free-form text of any kind.
+- No command arguments — only whitelisted command/skill *names*, and only
+  from the shipped roster (anything else is reduced to `"other"`).
+- No hostnames.
+- No IP addresses stored. The ingest server uses the requester's IP
+  **transiently, in memory, only** to enforce a per-IP rate limit — it is
+  never written to disk, and access logging is disabled on the telemetry
+  vhost.
+- No email addresses, no git author identity, no account identifiers.
+
+If a skill or command name isn't part of the plugin's own shipped roster —
+including any custom or third-party skill you've added locally — it never
+leaves your machine; it is projected to `"other"` before the payload is
+built.
+
+## Consent & kill switches
+
+Precedence, highest wins:
+
+1. **`DO_NOT_TRACK`** — any non-empty value except `0`/`false` disables
+   telemetry unconditionally. This is the industry-standard signal and
+   overrides everything else, including a fleet force-enable.
+2. **`SO_TELEMETRY_DISABLED=1`** — explicit per-shell disable.
+3. **`SO_TELEMETRY=1`** — explicit per-shell force-enable (used for fleet
+   testing without touching the consent file).
+4. **`owner.yaml` `telemetry.enabled`** — host-local fleet-mode opt-in (see
+   below); has no effect on a machine without that file.
+5. **Saved consent** — `~/.config/session-orchestrator/telemetry.json`,
+   written the first time you answer the consent prompt. Never inside any
+   repository, never committed.
+6. **First-run prompt** — shown at most once, **interactively only**. A
+   headless or CI invocation never shows this prompt and never sends
+   telemetry, regardless of any saved state.
+
+If the consent file is corrupt or unreadable, the client fails **closed**:
+telemetry state degrades to "no consent" (nothing sent) rather than
+guessing, with a one-line stderr hint pointing at the CLI below.
+
+**CLI:**
+
+```bash
+node scripts/telemetry.mjs status    # show current consent + kill-switch state
+node scripts/telemetry.mjs enable    # opt in
+node scripts/telemetry.mjs disable   # opt out
+node scripts/telemetry.mjs show      # print the last built payload, don't send
+```
+
+**Debug flag:** set `SO_TELEMETRY_DEBUG=1` to print the exact payload that
+*would* be sent to stderr instead of sending it — useful for verifying the
+whitelist projection yourself before ever trusting it.
+
+**Fleet mode.** An operator running many repos on one host can set
+`telemetry.enabled: true` (and optionally `telemetry.fleet: true`) in their
+own `owner.yaml` — a host-local, never-committed file outside every repo —
+to enable telemetry across all adopted repos without a per-repo prompt.
+Records sent this way carry `fleet: true`. `DO_NOT_TRACK` and
+`SO_TELEMETRY_DISABLED=1` still win over fleet mode in the same shell.
+
+## Where it goes
+
+Consented payloads are sent as a batched `POST` to:
+
+```
+https://telemetry.session-orchestrator.com/v1/records
+```
+
+This endpoint is operated by the plugin's maintainer. The server-side code
+is open source in this same repository, under `server/ingest/` — a
+dependency-light Node service that validates the payload against the
+per-`record_kind` schema, stores it in SQLite, and rejects anything that
+doesn't fit the schema (unknown `record_kind`, oversized body, or a schema
+violation). There is no third-party analytics vendor in this path — no
+Segment, no Mixpanel, no Google Analytics.
+
+The send is fire-and-forget with a short timeout; if the endpoint is
+unreachable, the batch queues locally (bounded size, oldest entries dropped
+first) and retries later. Telemetry never blocks or slows down a session
+beyond that short timeout budget.
+
+## Retention
+
+- **Raw records:** kept 24 months, then pruned. The retention window exists
+  to support year-over-year product decisions (what to deepen, what to
+  sunset) without keeping data indefinitely.
+- **Aggregates:** kept indefinitely; aggregates carry no record-level
+  identifiers by construction.
+- **Anonymous ID rotation:** every 90 days, independent of retention — a
+  rotated ID cannot be linked back to the one it replaced.
+
+## Schema evolution
+
+The schema is **additive-only** within a given `schema_version`: new
+optional fields may appear, but no field is ever repurposed or removed
+without a version bump. The server accepts both the current and the
+immediately previous `schema_version`, so a slightly-outdated client is
+never hard-broken by a server-side schema update.
+
+## Relationship to `telemetry-claims.md`
+
+This page describes the **opt-in, client-side usage-telemetry pipeline**
+above. It is a distinct data flow from
+[`docs/telemetry/telemetry-claims.md`](telemetry/telemetry-claims.md), which
+documents the methodology behind the maintainer's separate **local, private**
+metrics aggregates (`.orchestrator/metrics/*.jsonl`, gitignored, never
+transmitted anywhere) used in marketing claims such as "645 orchestrated
+sessions." Neither pipeline feeds the other.