session-orchestrator 3.16.0 → 3.17.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi.",
-    "version": "3.16.0"
+    "version": "3.17.0"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "session-orchestrator",
-  "version": "3.16.0",
+  "version": "3.17.0",
   "description": "Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi.",
   "author": {
     "name": "Bernhard Goetzendorfer",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "session-orchestrator",
-  "version": "3.16.0+codex.20260719182053",
+  "version": "3.17.0+codex.20260721060103",
   "description": "Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on Claude Code, Codex CLI, Cursor, and Pi.",
   "keywords": [
     "session",

package/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.17.0] - 2026-07-21
+
+Telemetry & curation release. Headline: **opt-in anonymous usage telemetry** (#841) — a
+consent-gated client with anonymous IDs, a local queue, and a record_kind-generic ingest
+path, off by default — alongside the **vault-curation probe trio** (#831 B2/B4/B5), the
+completed abandoned-session sweep, and a review-panel/gates hardening pass. The npm
+distribution line is complete: this release ships the `npm-publish` token-runbook skill
+distilled from the v3.16.0 first publish (#825) plus broadened registry metadata.
+
+### Added
+
+- **Opt-in anonymous usage telemetry (#841)** — `scripts/lib/telemetry/` (`anon-id`, `consent`, `queue`, `schema`, `sync`): consent-gated client with anonymous IDs and a local queue, record_kind-generic ingest, `flush()` with `ownerConfig` injection for hermetic tests. Off by default; PRD at `docs/prd/2026-07-20-anonymous-usage-telemetry.md`.
+- **Vault-curation probes B2/B4/B5 (#831)** — `moc-staleness` (frontmatter-`updated:` MOC banner), `context-coverage` (registered projects missing `context.md`/`_passive.md`), `worktree-orphans` (candidates-only sweep — never deletes, PSA-003) — all opt-in via Session Config; abandoned-session sweep completed.
+- **`skills/npm-publish/`** — token-based publish runbook (granular-token requirements, temp-userconfig flow, leakage gates, failure-mode table) distilled from the v3.16.0 first publish (#825).
+
+### Fixed
+
+- **Review-panel findings** — base-branch injection in diff-range resolution, fail-open quality gates, torn-write `jq` invocation, inert analyzer wiring.
+- **vault-sync register/mode + abandoned-session signal integrity** — register/mode vocabulary alignment, enumerate scan depth, signal-integrity guards on the abandoned-session sweep.
+- **Telemetry `flush()`** — accepts `ownerConfig` injection so hermetic tests never read the host `owner.yaml`.
+
+### Changed
+
+- **npm discoverability** — broadened `keywords` + explicit `bugs` field in `package.json`.
+
 ## [3.16.0] - 2026-07-19
 
 Hardening release. Headline: the **bold-key parser fix goes class-wide** — a shared

package/README.md

@@ -1,7 +1,8 @@
 # Session Orchestrator
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-3.16.0-blue.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-3.17.0-blue.svg)](CHANGELOG.md)
+[![npm](https://img.shields.io/npm/v/session-orchestrator.svg)](https://www.npmjs.com/package/session-orchestrator)
 [![Tests](https://img.shields.io/badge/tests-10%2C000%2B-brightgreen.svg)](docs/telemetry/telemetry-claims.md)
 
 Loop engineering for AI coding agents — turn ad-hoc sessions into a repeatable research → plan → wave-execute → close loop with verification gates. Runs on **Claude Code, Codex CLI, Cursor, and [Pi](docs/pi-setup.md)**.
@@ -17,7 +18,7 @@ The same skills and commands run across all four, with platform-adapted hooks an
 | **Claude Code** | `/plugin marketplace add Kanevry/session-orchestrator` then `/plugin install session-orchestrator@kanevry` (run both inside Claude Code). Also listed on the official community catalog: `/plugin install session-orchestrator@claude-community` (that catalog can lag HEAD). |
 | **Codex CLI** | `git clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator && cd ~/Projects/session-orchestrator && npm install && node scripts/codex-install.mjs` |
 | **Cursor IDE** | `git clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator && cd ~/Projects/session-orchestrator && npm install && node scripts/cursor-install.mjs /path/to/your/project` |
-| **Pi** | `git clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator && cd ~/Projects/session-orchestrator && npm install && node scripts/pi-install.mjs /path/to/your/project --settings-only` (npm path `pi install npm:session-orchestrator` lands once published — not yet available) |
+| **Pi** | `pi install npm:session-orchestrator` — or dev-fallback: `git clone https://github.com/Kanevry/session-orchestrator.git ~/Projects/session-orchestrator && cd ~/Projects/session-orchestrator && npm install && node scripts/pi-install.mjs /path/to/your/project --settings-only` |
 
 For Claude Code, also install Node dependencies **once** (hooks import `zx`) and restart Claude Code:
 
@@ -65,7 +66,7 @@ Everything else is opt-in. See [`docs/session-config-template.md`](docs/session-
 
 ## What you get
 
-- **44 skills** for the session lifecycle (start, plan, execute, close, evolve), discovery, vault sync, MCP authoring, debugging, brainstorming, plan grilling, persona panels, cross-repo dispatch, learning→rule reconciliation, session-process eval, audits, and more
+- **45 skills** for the session lifecycle (start, plan, execute, close, evolve), discovery, vault sync, MCP authoring, debugging, brainstorming, plan grilling, persona panels, cross-repo dispatch, learning→rule reconciliation, session-process eval, audits, and more
 - **24 slash commands** (`/session`, `/go`, `/close`, `/discovery`, `/plan`, `/grill`, `/evolve`, `/autopilot`, `/dispatcher`, `/reconcile`, `/eval`, `/test`, `/debug`, …)
 - **15 typed subagents** (code-implementer, test-writer, security-reviewer, session-reviewer, qa-strategist, architect-reviewer, …)
 - **10 hook event types** enforcing scope, blocking destructive commands, gating templates-first, capturing telemetry — full on Claude Code; experimental, post-hoc, or bridged on the other platforms ([Platform support](#platform-support))
@@ -126,16 +127,16 @@ The system is markdown-driven config plus a thin Node runtime — skills, comman
 - **Cross-session learning is opt-in and inspectable.** Every session writes a record; after 5+ sessions `/evolve analyze` extracts confidence-scored patterns you can read and prune. Nothing is hidden.
 - **VCS dual support, no lock-in.** Auto-detects GitLab or GitHub from your remote and drives the full lifecycle for both.
 
-## Recent highlights (v3.16.0)
+## Recent highlights (v3.17.0)
 
-Every release is additive and backward-compatible. Highlights of the v3.16.0 line:
+Every release is additive and backward-compatible. Highlights of the v3.17.0 line:
 
-- **Class-wide bold-key parser fix (`matchBlockHeader`)** — the `- **key:**` blind spot #823 fixed for one parser is now closed across all 34 Session-Config block parsers via a shared zero-import helper, with the inline-comment gotcha and drift-check raw-parity preserved.
-- **Vault-namespace de-collapse (`VAULT_CLEAR_SLUGS`)** — already-public repo slugs regain distinct vault namespaces (no more shared `redacted-repo/` bucket) while the public-mirror tracked-file scanner keeps blocking all private slugs.
-- **Vault board TTL self-healing** — preserved in-progress rows past the heartbeat TTL now flip to `force-closed`; narrative folders loose-match existing `01-projects/` folders instead of minting duplicates.
-- **Actionable freshness remediation (`/bootstrap --refresh-lock`)** — reason-aware banners plus a provenance-honest lock refresher (only two refresh fields written, original bootstrap provenance byte-identical).
+- **Opt-in anonymous usage telemetry (#841)** — consent-gated client (`scripts/lib/telemetry/`) with anonymous IDs, a local queue, and record_kind-generic ingest. Off by default; nothing leaves the machine without explicit opt-in.
+- **Vault-curation probes (#831 B2/B4/B5)** — MOC-staleness banner, context-coverage line, and a candidates-only worktree-orphan sweep (never deletes — PSA-003), plus the completed abandoned-session sweep.
+- **Review-panel & gates hardening** — base-branch injection, fail-open quality gates, torn-write `jq`, vault-sync register/mode vocabulary, and enumerate scan depth fixed in one pass.
+- **npm distribution line complete** — first publish shipped (v3.16.0 on npm, #825); this line adds the `npm-publish` token-runbook skill and broadened registry metadata.
 
-Previous line (v3.15.0): `/eval` session-process evaluation (standard v1), out-of-scope shell-write guard, per-context `baselines:` in owner.yaml, `bash-harness-pitfalls` rule, distribution foundation (landing page + submission kit), parser/config hardening bundle.
+Previous line (v3.16.0): class-wide bold-key parser fix (`matchBlockHeader`), vault-namespace de-collapse (`VAULT_CLEAR_SLUGS`), vault-board TTL self-healing, provenance-honest `/bootstrap --refresh-lock`.
 
 Full version history: [CHANGELOG.md](CHANGELOG.md).
 
@@ -208,7 +209,7 @@ What it is **not**:
 
 - **Not an official product of any agent vendor.** An independent, community-maintained project — not affiliated with, endorsed by, or sponsored by Anthropic, OpenAI, Cursor, or any agent it integrates with. (It is distributed through the Claude Code plugin marketplace, but is not an Anthropic product.)
 - **Not a replacement** for Claude Code / Codex CLI / Cursor / Pi. It is a workflow layer that runs *on top of* your existing agent — you still need one of those installed.
-- **Not a hosted service.** Runs locally — no server, account, or cloud component.
+- **Local by default.** Runs locally — no account required. Optional, strictly opt-in anonymous usage telemetry (off until you consent; see [docs/telemetry.md](docs/telemetry.md)).
 - **No guarantee that telemetry numbers transfer to your repo.** Reported test counts and metrics describe *this* repository under its own conditions ([details](docs/telemetry/telemetry-claims.md)). Your results will vary by stack, project size, and configuration.
 
 ## Documentation
@@ -218,6 +219,7 @@ What it is **not**:
 - [Components & Reference](docs/components.md) — full skill/command/agent/hook inventory, repository anatomy, comparisons
 - [Plugin Architecture (v3)](docs/plugin-architecture-v3.md) — contributor guide, layering, hook anatomy, testing
 - [Migration to v3](docs/migration-v3.md) — upgrade path from v2.x, known issues, rollback
+- [Telemetry](docs/telemetry.md) — what the optional opt-in usage telemetry collects, and how to turn it off
 - [Telemetry claims](docs/telemetry/telemetry-claims.md) — how reported metrics are measured, and why they may not transfer
 - [Example Configs](docs/examples/) — Session Config examples for Next.js, Express, Swift
 - [CHANGELOG.md](CHANGELOG.md) — version history

package/docs/README.md

@@ -91,7 +91,8 @@ Two things worth knowing about this split:
 | `docs/examples/` | Living reference | Example Session Config blocks per project shape (Express API, integration test, Next.js, Swift/iOS). |
 | `docs/recipes/` | Living reference | Narrow how-to write-ups for a specific recurring pattern (e.g. the quality-gate container test-runner pattern). |
 | `docs/templates/` | Living reference | Copy-paste config snippets referenced directly by the setup guides (e.g. the `AGENTS.md` Session Config template). |
-| `docs/telemetry/` | Living reference | `telemetry-claims.md` — provenance/methodology notes for cross-repo telemetry numbers cited elsewhere in the docs. |
+| `docs/telemetry.md` (root) | Living reference | Public transparency page for the opt-in usage-telemetry client — exact field list, kill switches, consent precedence, retention. |
+| `docs/telemetry/` | Living reference | `telemetry-claims.md` — provenance/methodology notes for cross-repo telemetry numbers cited elsewhere in the docs (a separate, local-corpus data flow from the opt-in client telemetry above). |
 | `docs/adr/` | Public decision history | Architecture Decision Records — permanent, never archived, cited externally. |
 | `docs/prd/` | Active work document | PRDs of currently open epics only. Auto-archived to the Meta-Vault on epic close. |
 | `docs/plans/` | Active work document | `/write-executable-plan` artifacts for in-progress work. May not exist when nothing is mid-plan. |

package/docs/components.md

@@ -18,7 +18,7 @@ flowchart LR
     COORD -->|writes| METRIC[.orchestrator/metrics/<br/>sessions · learnings · events]
 ```
 
-## Skills (44 user-facing)
+## Skills (45 user-facing)
 
 - **Lifecycle:** `session-start`, `session-plan`, `wave-executor`, `session-end`, `quality-gates`, `using-orchestrator`
 - **Authoring:** `skill-creator`, `mcp-builder`, `hook-development`, `frontmatter-guard`
@@ -26,7 +26,7 @@ flowchart LR
 - **Architecture:** `architecture`, `domain-model`, `ubiquitous-language`
 - **Cross-session:** `evolve`, `convergence-monitoring`, `memory-cleanup`, `reconcile`, `sunset-review`, `eval`
 - **Vault & docs:** `vault-sync`, `vault-mirror`, `daily`, `docs-orchestrator`
-- **Ecosystem:** `bootstrap`, `gitlab-ops`, `gitlab-portfolio`, `ecosystem-health`, `mode-selector`, `autopilot`, `dispatcher`, `spinout`
+- **Ecosystem:** `bootstrap`, `gitlab-ops`, `gitlab-portfolio`, `ecosystem-health`, `mode-selector`, `autopilot`, `dispatcher`, `spinout`, `npm-publish`
 - **Testing:** `test-runner`, `playwright-driver`, `peekaboo-driver`
 - **Content review:** `persona-panel`
 - **Visualization:** `tmux-layout` (opt-in operator side-channel — [ADR-0007](adr/0007-tmux-visualization-substrate.md))

package/docs/pi-setup.md

@@ -16,7 +16,7 @@ Guide for using Session Orchestrator with [Pi](https://pi.dev/docs/latest).
 pi install npm:session-orchestrator
 ```
 
-This is the primary install path once the package has been published to npm and indexed by the [Pi packages gallery](https://pi.dev/packages) via its `pi-package` keyword — no local checkout required. Not yet available: the package has not been published to npm yet (see `docs/distribution/npm-publish-checklist.md` for the operator publish runbook). Until then, use one of the dev-fallback options below.
+This is the primary install path — the package is published to npm (since v3.16.0, 2026-07-19) and carries the `pi-package` keyword for the [Pi packages gallery](https://pi.dev/packages) index; no local checkout required. The dev-fallback options below remain available for working against a local checkout.
 
 ### Option 2: Project-local registration (dev fallback)
 

package/docs/session-config-reference.md

@@ -785,6 +785,71 @@ docs-staleness:
 
 **Used by:** `skills/discovery/probes/docs-staleness.mjs` (`runProbe`), `scripts/lib/config/docs-staleness.mjs` (`_parseDocsStaleness`). Writes one JSONL summary record per run to `.orchestrator/metrics/docs-staleness.jsonl`. See `docs/README.md` for the living-vs-archived docs classification this probe enforces.
 
+## MOC Staleness (#831/B2)
+
+Opt-in session-start banner probe for Obsidian "map of content" index notes — `<vault>/08-topics/*-moc.md` whose frontmatter `updated:` is older than the threshold. Complements `vault-staleness` (which covers project narratives) by covering the topic index layer. Rendered at session-start Phase 4 alongside the other banners; never blocks a session.
+
+```yaml
+moc-staleness:
+  # Parser gotcha: this key line must carry NO inline comment.
+  enabled: false                       # opt-in
+  thresholds:
+    moc: 90                            # days — frontmatter `updated:` staleness threshold
+  mode: warn                           # warn | off
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `moc-staleness.enabled` | boolean | `false` | Must be explicitly `true` to activate. The gate fails CLOSED — a missing block, a missing `enabled` key, or an omitted `config` argument all return `null` before any filesystem I/O. |
+| `moc-staleness.thresholds.moc` | integer (days) | `90` | Age threshold measured against frontmatter `updated:`. Non-numeric or non-positive values fall back to the default. |
+| `moc-staleness.mode` | string | `warn` | `warn` \| `off`. A malformed value falls back to `warn`. |
+
+A MOC whose `updated:` is **missing or unparseable is deliberately EXCLUDED**, not reported as stale — the corrective action there is "fix the frontmatter", not the banner's own hint. Same rule as `scripts/lib/peer-cards/staleness-banner.mjs`.
+
+**Used by:** `scripts/lib/moc-staleness-banner.mjs` (`checkMocStaleness`), `scripts/lib/config/moc-staleness.mjs` (`_parseMocStaleness`). Wired at `skills/session-start/SKILL.md` Phase 4.
+
+## Context Coverage (#831/B4)
+
+Opt-in session-start coverage banner: registered `<vault>/01-projects/<slug>/` folders that carry **neither** `context.md` nor `_passive.md`. A project counts as *registered* iff its folder contains `_overview.md` — the same convention `discoverVaultRepos()` uses (`scripts/lib/gitlab-portfolio/vcs-detect.mjs`). Folders lacking `_overview.md` are never counted and never reported as gaps.
+
+```yaml
+context-coverage:
+  # Parser gotcha: this key line must carry NO inline comment.
+  enabled: false                       # opt-in
+  mode: warn                           # warn | off
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `context-coverage.enabled` | boolean | `false` | Must be explicitly `true` to activate. Fails CLOSED, as above. |
+| `context-coverage.mode` | string | `warn` | `warn` \| `off`. A malformed value falls back to `warn`. |
+
+**Used by:** `scripts/lib/context-coverage-banner.mjs` (`checkContextCoverage`), `scripts/lib/config/context-coverage.mjs` (`_parseContextCoverage`). Wired at `skills/session-start/SKILL.md` Phase 4.
+
+## Worktree Orphans (#831/B5)
+
+Opt-in session-end sweep (Phase 4b) identifying git worktree branches with **0 commits ahead of the base branch** — leftovers from finished sessions. The module **proposes; it never disposes**: it returns `candidates` and the coordinator renders the removal AUQ. Nothing is removed without explicit operator confirmation (PSA-003).
+
+```yaml
+worktree-orphans:
+  # Parser gotcha: this key line must carry NO inline comment.
+  enabled: false                       # opt-in
+  base-branch: main                    # ref the ahead-count is measured against
+  mode: warn                           # warn | off
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `worktree-orphans.enabled` | boolean | `false` | Must be explicitly `true` to activate. Fails CLOSED — a repo that never opted in pays no git invocation. |
+| `worktree-orphans.base-branch` | string | `main` | Ref the ahead-count is measured against. **Validated:** a value beginning with `-`, or containing whitespace or shell metacharacters, is rejected and falls back to `main`. |
+| `worktree-orphans.mode` | string | `warn` | `warn` \| `off`. A malformed value falls back to `warn`. |
+
+**Why `base-branch` is validated rather than passed through.** It reaches an argv position in `git rev-list --count <base>..<branch>`. A value shaped like a git flag (e.g. `--glob=refs/heads/*`) is parsed as an OPTION rather than a revision range, exits 0, and prints `0` — silently marking **every** worktree as a 0-ahead orphan and offering the operator a deletion prompt for worktrees full of live work. The conservative default does not catch it, because `0` parses fine. Defence is two-layer: the parser rejects leading-dash values, and the sink passes `--end-of-options` so any surviving payload becomes a hard git error. This makes `base-branch` a **fifth command-influencing Session Config surface** beyond the four listed in `.claude/rules/security.md` § "Session Config Command Trust" — and unlike those, no attacker is required: a typo reaches the same outcome.
+
+A worktree holding uncommitted, staged or untracked work is **never** a candidate — `isWorktreeClean()` (the Phase 4a helper) is consulted first, and any git error while checking excludes the worktree conservatively.
+
+**Used by:** `scripts/lib/session-end/worktree-orphan-sweep.mjs` (`checkWorktreeOrphans`), `scripts/lib/config/worktree-orphans.mjs` (`_parseWorktreeOrphans`, `_isSafeBaseBranch`). Wired at `skills/session-end/SKILL.md` Phase 4b.
+
 ## Docs Orchestrator
 
 Opt-in configuration for the `docs-orchestrator` skill, which generates audience-split documentation (User / Dev / Vault) within sessions (see `skills/docs-orchestrator/SKILL.md`). When enabled, session-start runs a Phase 2.5 docs-context step, session-plan assigns a Docs role, and session-end runs a Phase 3.2 gap-reporting step. The `docs-writer` agent is made available automatically when `enabled: true`.

package/docs/session-config-template.md

@@ -466,6 +466,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`.
@@ -820,6 +835,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:

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.