session-orchestrator 3.16.0 → 3.19.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.19.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.19.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.19.0+codex.20260804175819",
   "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/.cursor/rules/030-wave-execution.mdc

@@ -73,7 +73,23 @@ Role-specific scope rules:
 - **Quality Phase 1 (Simplification)**: production files changed this session only (no test files)
 - **Quality Phase 2 (Tests)**: test file patterns only (`**/*.test.*`, `**/*.spec.*`, `**/__tests__/**`)
 
-Validate with: `bash "$CURSOR_RULES_DIR/../scripts/validate-wave-scope.sh"` — fix JSON if it exits 1.
+**Test-sibling expansion (#970):** a scope entry naming a production file but not its test sibling makes the task's own regression test unwritable — the guard then enforces exactly the inconsistency the quality gate exists to catch. Before writing `allowedPaths`, expand the union through the shared helper — do not hand-derive the paths:
+
+```js
+import { expandTestSiblings } from '$CURSOR_RULES_DIR/../scripts/lib/scope-gate.mjs';
+// Pass this wave's role verbatim — the helper GATES on it.
+const allowedPaths = expandTestSiblings(unionScopes, { role });
+```
+
+It emits a **glob** from the production basename (`foo.mjs` → `tests/**/foo*.test.mjs`), skips absolute entries, and is a strict no-op on Discovery's `[]`. **Which roles it fires for is decided inside the helper** — `TEST_SIBLING_EXPANSION_ROLES` in `scripts/lib/scope-gate.mjs` (currently Impl-Core / Impl-Polish; Quality Phase 1 is off, Phase 2 inert). Pass the role; do not pre-filter by role here. An absent or unrecognised role does **not** expand (fail-closed). Expand before the overlap check and before the file is written, in one pass. Full rule, the measured hit-rate and its ~15% residual, and the per-repo configurability: `skills/wave-executor/wave-loop.md` § Scope Manifest #3.
+
+Validate with: `node "$CURSOR_RULES_DIR/../scripts/validate-wave-scope.mjs" < .cursor/wave-scope.json` — fix JSON if it exits 1. Before each task batch, also assert the task's file scope against the manifest, carrying the mechanical half of the rule above (gated on the manifest's `role`, so it self-skips where expansion does not fire):
+
+```bash
+node "$CURSOR_RULES_DIR/../scripts/validate-wave-scope.mjs" \
+  --assert-subset "$TASK_FILESCOPE_JSON" --expand-test-siblings \
+  < .cursor/wave-scope.json
+```
 
 ### Step 2: Execute Tasks Sequentially
 

package/CHANGELOG.md

@@ -5,6 +5,130 @@ 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).
 
+## [Unreleased]
+
+## [3.19.0] - 2026-08-04
+
+Guard-hardening and release-mechanics line. Headline: the destructive-command guard closed
+six measured wrapper bypasses and inverted a silent redirect-truncation allow into a deny;
+the session lock gained an ownership proof; and the release process itself became one
+dispatch — whose very first preflight run surfaced that v3.18.0 had been tagged but never
+published to npm (the registry still served 3.17.0), the exact incident class #978 names.
+
+### Added
+
+- **`scripts/release.mjs` — Release als ein Dispatch (#978, local half)** — one surfaces
+  table drives both the mechanical version rewrite (`--set-version`: 12 version literals
+  across 10 files, Codex cachebuster rotation, package-lock sync) and the preflight
+  (`--check`: surface parity with pattern-dead-is-a-failure semantics, CHANGELOG entry +
+  folded-[Unreleased] gate, tag collision on local/origin/github, npm-registry collision,
+  a `git grep` drift sweep over ALL tracked files, CI-green-on-HEAD via
+  `ci-status-banner.mjs`, the seven-pattern leakage gate over `npm pack --dry-run`).
+  `--publish` runs the token flow from `skills/npm-publish/SKILL.md` and creates the
+  annotated git tag only AFTER a registry-verified publish — eliminating the
+  "tagged but unpublished" state v3.18.0 fell into. Its first run surfaced two real gaps:
+  v3.18.0 was tagged but never published to npm (the registry served 3.17.0), and the
+  hidden `.codex-plugin` manifest was invisible to a plain ripgrep census — hidden
+  directories need `git grep`. The CI half of #978 (a `$CI_COMMIT_TAG` release stage)
+  stays open.
+- **`skills/contract-version-bump/`** — reusable, distributable skill for version-bumping machine-readable contracts (JSON Schema, API specs, config schemas): classifies the change against the contract's OWN versioning rule (not generic semver instinct), finds every version literal and vendored copy across this repo and `cross-repos:`, checks whether every known consumer evaluates each new/changed schema keyword, applies the bump consistently, writes a Keep-a-Changelog entry, and reports downstream drift. Codifies three traps from a real case (GitLab issue #17, `aiat-enablement` repo, 2026-07-25). Ships with `/contract-version-bump`.
+- **Wrapper unwrapping in the destructive-command guard (#982)** — table-driven
+  `WRAPPER_UNWRAP` (`sudo`/`doas`/`env` flags/`nohup`/`timeout`/`nice`/`stdbuf`,
+  `sudo -i/-s` → sh, `su` as interpreter) plus depth-capped `-c`/`env -S` payload
+  recursion; `rm` parsers rewritten segment-based on the shared splitter. Six measured
+  bypasses closed, zero regressions (differential-proved).
+- **Blocked-commands policy floor (#972)** — new `scripts/lib/blocked-commands-policy.mjs`
+  with floor ∪ overlay semantics: escalate-only, whole-rule-wins on block collisions,
+  fail-to-floor on empty/malformed overlays. Replaces first-hit-wins.
+- **Redirect target denylist (#983)** — new redirect token class (longest-match
+  `&>>`/`&>`/`>|`/`>>`/`>`/`N>`-forms) and rule 14 `redirect-truncate-protected`: the
+  premise was inverted — `&> CLAUDE.md` was a silent ALLOW-with-truncation before.
+- **Session-lock ownership proof (#987)** — owner proof persisted at lock genesis
+  (`.orchestrator/runtime/lock-owner-proof.json`); session-end releases only on
+  self-rotation and refuses foreign same-day collisions — closes the #926 residual.
+- **session-orchestrator.com redesign** — terminal hero, wave pipeline, leaderboard shell,
+  measured-numbers section (reconcile-rule count corrected 11 → 13 by the close-review).
+
+### Fixed
+
+- **Guard bypass residuals (three follow-up rounds)** — the denylist read repo-relative
+  while an attacker wrote absolute paths; the guard evaluated the working tree instead of
+  the rules corpus; a backslash split what bash glues together; and the review panel found
+  two further holes the repair session had itself opened. Each round closed with
+  fake-regression proofs.
+- **Session identity (#926, #914)** — an ending session no longer deletes a living foreign
+  session lock, and the abandoned-session backfiller no longer deletes the alarm it was
+  built to raise.
+- **Instrument deduplication** — nine instances of one fact wearing two faces consolidated
+  to single sources; the panel found three more in the repair itself.
+- **Reconcile expiry tests** — two tests measured the floor constant instead of
+  `ruleExpiryDays`; they now measure the contract.
+
+### Security
+
+- **Two high-severity transitive vulnerabilities** unreachable by `npm audit fix` closed
+  via `package.json` overrides (same class, found twice — the second instance surfaced
+  after the first override landed).
+
+## [3.18.0] - 2026-07-31
+
+Panel-follow-ups & consolidation release. Headline: the review panel's own findings from the
+prior deep session, fixed and re-verified — three self-silencing vectors closed in the
+bash-write-verify scope detector, a credential that could no longer reach argv, and the
+instrument deduplication the panel asked for — alongside an instruction-corpus diet (always-on
+directive budget 471→~440) and a TV-003 consolidation tranche (net test count down, catch-power
+up via a mutation sweep). The panel found real bugs in this session's own coordinator-written
+code again — the sixth consecutive confirmation — and W5 fixed all four.
+
+### Added
+
+- **Instruction-delivery measurement + baseline ablation axis (#936)** — `evals/instruction-ablation/run.mjs` gains a `--rules-source repo|baseline` switch (host-local precedence, no hardcoded path) so one command ablates the fleet-wide `projects-baseline` corpus; the decision rule is pre-registered in `docs/instruction-delivery.md §6`, fail-safe toward KEEP because a wrong cut regresses fourteen repos.
+- **hooks-symmetry Check 6 (#942)** — `check-hooks-symmetry.mjs` now compares handler SETS per event, not just event keys, so a hook wired on only one platform is no longer structurally invisible; `post-bash-write-verify` ported to Pi, Codex documented as an exception.
+- **Mutation-testing sweep (#910)** — 8 modules, 46 mutants, 70% kill-rate; eight need-gated tests close the highest-value survivors (boundary comparisons + wiring/fail-safe), report at `docs/mutation-testing/`.
+- **CPU 5-minute load axis (#943)** — `resource-probe` emits `cpu_load_5m`/`cpu_load_5m_pct`; the wave resource gate judges CPU on `min(1m, 5m)` so it no longer halves a wave on the decaying 1-minute average of its own just-finished quality run.
+- **Two glob-scoped reconcile rules** — `a-green-quality-gate-is-not-CI-evidence` and `a-file-wide-toContain-judges-one-block` (both conditional, zero always-on ceiling cost); the bash-3.2 `case`-in-`$()` gotcha folded into `bash-harness-pitfalls.md`.
+- **CI advisory job `test-value-bans`** — non-blocking, runs the narrowed ban scanner; `.husky/pre-push` gate + schema-drift marker guard now have tests (#940).
+
+### Fixed
+
+- **#907 credential leak (CWE-214)** — remote-URL credentials are stripped at the single source (`resolveRawRemoteUrl`) before reaching any `-R`/`--repo`/`--hostname` argv position or verbose log. The W4 panel then found the first fix incomplete for a raw `@` inside the token (`user:gl@token@host`); the userinfo class now binds to the LAST `@` before the authority ends, closing the residual. A bare `git@host` SSH login is left untouched.
+- **#938 bash-write-verify self-silencing (3 vectors)** — the control file left the hook's own ignore list; the gate is read from the recorded snapshot, not the live file; a re-baseline reports out-of-scope dirt via mtime. W4-panel follow-through: the `isMain` guard now realpath's both sides (a symlinked plugin install no longer silently disables the hook), and the mtime re-baseline uses `>=` with the scope file excluded (equal-mtime false-negative closed).
+- **#914 fabricated completion timestamp** — the abandoned-session backfill no longer stamps the backfill-run wall-clock as `completed_at` (which produced ~64h of phantom runtime on real records); it uses the last events-attested timestamp with a `_completed_at_estimated` flag.
+- **#939 orphan telemetry records** — the `subagents.jsonl` orphan-stop class (harness-side phantom SubagentStops) is documented on BOTH the lifetime (51%) and running-window (~93%) numbers, with a `start_record_found` write-time discriminator.
+- **#911 check-test-value-bans over-reporting + ReDoS** — B1 narrowed from 352 findings to 9 (dynamic-derived counts only), the length regex hardened from >2min to 0ms on pathological input, and B4 extended with a scope-gated `systemMessage` key.
+- **#886 eight instruction contradictions (C-1…C-8)** resolved against the code; the C-3 divergence (code-implementer test-writing ban vs the wave-executor's need-gated briefing) reconciled to the need-gated model on both surfaces.
+
+### Changed
+
+- **Instruction-corpus diet** — always-on directive budget 471→~440/480: `loop-and-monitor.md` pointer-ised into ADR-0010 (71→37 directives, body halved) with all eight delta-sync footers preserved (#885); `lsp.md`/`owner-persona.md`/`quality-gates-autofix.md` trimmed to pointers (#884).
+- **TV-003 consolidation** — 51 prose-presence pin tests removed and one implementation-mirror deleted (#912-T1); `config.test.mjs` split into seven feature-domain files (151 tests preserved); tests:src 1.7135→1.69.
+- **Chores** — test badge floor `12,000+`, `.vault.yaml` techStack `bash`→`nodejs`, CHANGELOG archive split into `docs/changelog/`.
+
+## [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
@@ -1127,418 +1251,12 @@ Three vault-sync commits (`a76e180`, `e3c8e47`, `82be589`) landed alongside the
 - Developer prerequisite: Node 20+ and `npm ci` after clone. Existing bash test suite (`scripts/test/run-all.sh`) continues to work on Unix while the foundation stabilizes; Windows users run `npm test` only.
 - No user-visible breakage yet. Hook migrations in later waves will require `npm install` in the plugin directory before hooks fire.
 
-## [2.0.0] - 2026-04-17
-
-First stable release of the 2.x line. Bundles six betas worth of work into a single stable cut.
-
-### Added
-- **Bootstrap Gate** (beta.6): non-bypassable Phase-0 check that prevents orchestrator skills from running against unstructured repos. Three tiers (Fast/Standard/Deep), committed `.orchestrator/bootstrap.lock`, new `/bootstrap` command with `--fast`/`--standard`/`--deep`/`--upgrade`/`--retroactive` flags.
-- **Pre-dispatch grounding injection** (beta.5): prepends line-numbered GROUNDING blocks to agent prompts for files with recent `edit-format-friction` stagnation history, reducing Edit-tool retry loops. Per-agent scope, capped at `grounding-injection-max-files` (default 3), gated on `persistence: true`.
-- **Learnings-system efficiency** (beta.4): ranked cap on surfaced learnings (`learnings-surface-top-n`, default 15), passive confidence decay for untouched entries, surface-health telemetry in session-start, and retirement of the legacy split-brain `metrics/learnings.jsonl` path.
-- **Scope and command enforcement hardening** (beta.2): shared `scripts/lib/hardening.sh` module with per-gate toggles (`enforcement-gates`), actionable denial suggestions, stagnation pattern detection (Pagination Spiral, Turn-Key Repetition, Error Echo), and file-level grounding verification (`grounding-check`).
-- **Stagnation telemetry** (beta.2): session-end emits per-agent stagnation events with `pattern` and `error_class` fields; evolve accumulates these into `stagnation-class-frequency` learnings. Error-Class Taxonomy covers six classes.
-- **Clank Event Bus integration** (beta.1): async event emission for session start, stop, and agent stop events via `scripts/lib/events.sh`. Graceful degradation when unconfigured.
-- **Wave execution foundation** (alpha series): role-based wave assignment, adaptive sizing from complexity scoring, cross-session learning system, worktree isolation, circuit breaker with maxTurns and spiral detection, session persistence via STATE.md, PreToolUse enforcement hooks, and deterministic config parsing in `scripts/parse-config.sh`.
-
-### Changed
-- Marketplace install identifier is `session-orchestrator@kanevry` (renamed from the redundant `session-orchestrator@session-orchestrator` in beta.3).
-- Phase 0 of every orchestrator skill (`/plan`, `/session`, `/go`, `/close`, `/discovery`, `/evolve`) now runs the Bootstrap Gate before any other work.
-- Cross-session learnings are now ranked by confidence and capped before injection; entries that go untouched across sessions decay gradually rather than staying at full weight indefinitely.
-
-### Security
-- Placeholder substitution in bootstrap public-fallback templates uses Python `argv`, not `sed` string interpolation, to prevent injection via repo names.
-- Explicit file enumeration for `git add` in all bootstrap templates; no `git add -A` in generated commit steps.
-- `glab api` and `gh api` error output is redacted to prevent token leakage in hook logs.
-- Scope enforcement defaults to fail-closed (`strict`) when the `enforcement` field is absent from `wave-scope.json`.
-- `CLAUDE_PROJECT_DIR` is validated to contain a `.claude/` directory before being trusted by enforcement hooks.
-
-### Migration
-- Consumer repos with a legacy `<state-dir>/metrics/learnings.jsonl` file should run `bash <plugin>/scripts/migrate-legacy-learnings.sh` once after upgrading. The script is idempotent and produces a `.bak` copy of anything it touches.
-- The plugin install command changed in beta.3: use `/plugin marketplace add <source>` and `/plugin install session-orchestrator@kanevry` inside a running Claude Code session. There is no `claude plugin` shell command.
-
-## [2.0.0-beta.6] — 2026-04-16
-
-Issue #98 (Epic) — Bootstrap Gate. Addresses the "LLM rationalizes past hard-stops" problem: in a new empty repo, Codex bypassed the `/plan` skill's Phase-0 abort by falling back to "pragmatic paths", leaving the repo unstructured. The gate is a state-file-backed, cross-platform (Claude Code / Codex / Cursor), non-bypassable replacement. All 20 test suites pass.
-
-### Added — Bootstrap Gate (Epic #98)
-
-- **Non-bypassable Bootstrap Gate** (`skills/_shared/bootstrap-gate.md`) runs in Phase 0 of every orchestrator skill (`/plan`, `/session`, `/go`, `/close`, `/discovery`, `/evolve`). If a repo lacks `CLAUDE.md` + `## Session Config` + `.orchestrator/bootstrap.lock`, the gate invokes a new bootstrap flow.
-- **Three intensity tiers** — Fast (demos/spikes), Standard (MVPs/products), Deep (production/team). Each tier is a strict superset of the previous. LLM recommends tier from first user prompt; user confirms with one question.
-- **Public path** for users without a local `projects-baseline`: `claude init` (Claude Code) or plugin-bundled minimal templates (Codex, Cursor). Five archetypes: `_minimal`, `static-html`, `node-minimal`, `nextjs-minimal`, `python-uv`.
-- **Anti-bureaucracy guardrails** — exactly 1 question in normal flow, max 2 in ambiguous public path; idempotent gate check; committed `.orchestrator/bootstrap.lock` as mechanical truth.
-- **New `/bootstrap` command** with `--fast`/`--standard`/`--deep`/`--upgrade <tier>`/`--retroactive` flags.
-- **Six new test scripts** covering gate-check, tiers, upgrade, public path, idempotency, red-team.
-
-### Changed
-
-- Phase 0 Bootstrap Gate prepended to all 6 orchestrator skills (`plan`, `session-start`, `wave-executor`, `session-end`, `discovery`, `evolve`).
-
-### Security
-
-- Sanitized placeholder substitution in `skills/bootstrap/public-fallback.md` (Python argv, not sed string interpolation).
-- Explicit file enumeration for `git add` in all bootstrap templates (no `git add -A`).
-- Redacted `glab api` / `gh api` error output to prevent token leakage.
-- Follow-up issues #108 (LOW security) and #109 (MEDIUM+LOW tech-debt) filed for remaining hardening.
-
-### Motivation
-
-Addresses the "LLM rationalizes past hard-stops" problem: in a new empty repo, Codex bypassed the `/plan` skill's Phase-0 abort by falling back to "pragmatic paths", leaving the repo unstructured. The gate is a state-file-backed, cross-platform (Claude Code / Codex / Cursor), non-bypassable replacement.
-
-## [2.0.0-beta.5] - 2026-04-15
-
-Issue #85 — pre-dispatch grounding injection for friction-prone files. Direct translation of the Hashline idea from the *Harness Problem* abgleich (gap G3) to wave-executor's layer: when an agent's scope includes a file with recent `edit-format-friction` stagnation history (from #84 telemetry), the agent prompt is prepended with a line-numbered view of that file so the agent references lines stably instead of re-matching character spans. Per-agent scope, capped at `grounding-injection-max-files` (default 3), gated on `persistence: true`. All 14 script test suites remain green; integration fixtures grew from 107 to 122 assertions.
-
-### Added
-- feat(wave-executor): pre-dispatch grounding injection — prepend a line-numbered GROUNDING block to each agent's prompt for any file in the agent's scope that has recent `edit-format-friction` stagnation history (from #84 telemetry). Reduces Edit-tool retry loops by giving agents stable line-number references. Per-agent scope, capped at `grounding-injection-max-files` (default 3). Helper script `scripts/compute-grounding-injection.sh` (new); gated on `persistence: true`. Addresses Harness Problem gap G3. (#85)
-- feat(session-end): aggregate `grounding_injected` events into sessions.jsonl as `grounding_injections: {count, files, total_lines}`. Omitted when `count == 0`. (#85)
-- config: `grounding-injection-max-files` (integer, default `3`) — cap files injected per agent; set `0` to disable the feature. (#85)
-
-### Tests
-- test-integration.sh Group 12 (#85): 15 new assertions covering config default/override/disable, helper early-exit, match-and-emit, cap behavior with `grounding_capped=true`, and PERSISTENCE=false no-event-write path. Total integration assertions 107 → 122.
-
-## [2.0.0-beta.4] - 2026-04-15
-
-Epic #87 — learnings-system efficiency package. Four targeted changes to the cross-session intelligence layer that restore the original design intent: surface the most useful learnings, let irrelevant ones fade naturally, retire the legacy split-brain file, and make the whole thing transparent. Empirical baseline from a consumer repo (85 active learnings, ~13.6k tokens at every session-start) motivated the bundle. All 14 script test suites remain green; integration fixtures grew from 76 to 107 assertions.
-
-### Added
-- feat(session-start): rank and cap learnings injection — sort active learnings by confidence, slice to `learnings-surface-top-n` (default 15). Reduces Phase 5.6 token consumption on mature consumer repos. Configurable via Session Config key. Addresses Epic #87 / Issue #88. (#88)
-- feat(session-end): passive confidence decay for untouched learnings — subtract `learning-decay-rate` (default `0.05`) from every learning not confirmed, contradicted, or newly-appended this session. Applied before the existing prune step. `0.0` opts out. A learning starting at `0.5` survives ~10 untouched sessions. Addresses Epic #87 / Issue #89. (#89)
-- feat(session-start): "Surface health" sub-section in Project Intelligence — shows active/surfaced/suppressed counts, confidence distribution (high/medium/low), oldest surfaced entry, source file, vault mirror status. Prints an advisory when suppressed > surfaced. Addresses Epic #87 / Issue #91. (#91)
-
-### Fixed
-- fix(session-start): retire legacy `<state-dir>/metrics/learnings.jsonl` fallback — Phase 5.6 and `_shared/config-reading.md` now read ONLY the canonical `.orchestrator/metrics/learnings.jsonl`. Consumer repos with leftover legacy entries should run `scripts/migrate-legacy-learnings.sh` once. Addresses Epic #87 / Issue #90. (#90)
-
-  **MIGRATION**: in each consumer repo, run:
-
-      bash <plugin>/scripts/migrate-legacy-learnings.sh
-
-  where `<plugin>` is the session-orchestrator plugin directory. The script is idempotent, produces a `.bak` copy of any legacy file it touches, and emits a one-line JSON summary on stdout.
-
-### Tests
-- Added 31 integration-test assertions across 4 new fixture groups in `scripts/test/test-integration.sh`: Group 8 (cap+rank, #88, 6 assertions incl. equal-confidence tiebreaker), Group 9 (passive decay, #89, 3 assertions incl. IEEE-754 tolerance), Group 10 (surface health, #91, 8 assertions incl. positive + negative advisory), Group 11 (migration helper, #90, 13 assertions incl. empty-canonical, malformed-legacy, idempotency).
-- Added `json_float()` helper to `scripts/parse-config.sh` with regex + awk-based bounds validation (`0.0 ≤ x < 1.0` via strict-less-than max), covered by existing `test-parse-config.sh` suite.
-
-## [2.0.0-beta.3] - 2026-04-15
-
-Documentation patch release. No runtime code changes — all 16 script test suites remain green. End users and contributors can now successfully install the plugin through Claude Code for the first time since #14 shipped.
-
-### Changed
-- **Marketplace identifier** renamed from `session-orchestrator` to `kanevry` in `.claude-plugin/marketplace.json`. The plugin name itself remains `session-orchestrator`; this change only affects the suffix after `@` in the install command, so it reads `session-orchestrator@kanevry` instead of the redundant `session-orchestrator@session-orchestrator`. Existing local installs that registered the old marketplace name can remove it with `/plugin marketplace remove session-orchestrator` and re-add.
-- **Version string audit** — bumped every `2.0.0-beta.2` reference in sync: `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `.codex-plugin/plugin.json`, `hooks/hooks.json`, `hooks/hooks-codex.json`, `scripts/mcp-server.sh`, `README.md` version badge, `docs/USER-GUIDE.md` banner example, `CONTRIBUTING.md` hook example. Applies the version-string-drift learning from the beta.2 release-cut.
-
-### Fixed
-- **Install instructions** across `README.md`, `docs/USER-GUIDE.md`, and `CONTRIBUTING.md` referenced non-existent `claude plugin add` / `claude plugin install` shell commands. Claude Code has no such CLI — plugins install exclusively via the slash commands `/plugin marketplace add <source>` and `/plugin install <name>@<marketplace>` inside a running session. End users following the previous instructions could not install the plugin at all. Docs now show the correct slash-command flow for both GitHub and local-clone installs. This is a follow-up to #14, whose original fix in commit 802d821 introduced the incorrect commands.
-
-## [2.0.0-beta.2] - 2026-04-13
-
-### Added
-- **Shared hardening module** (GL#76) — `scripts/lib/hardening.sh` with pure, independently-testable helpers (`require_jq`, `source_platform`, `find_scope_file`, `get_enforcement_level`, `gate_enabled`, `path_matches_pattern`, `command_matches_blocked`, `emit_deny`, `emit_warn`, `suggest_for_*`). All three enforcement hooks now source this module instead of duplicating logic.
-- **test-hardening.sh** — 33 assertions covering path matching (directory prefix, `**`, single-segment glob, exact), command word-boundary matching, scope-file discovery, enforcement-level parsing, gate toggles, and suggestion content.
-- **Per-gate enforcement toggles** (GL#77) — new `enforcement-gates` Session Config field. Object with boolean values for `path-guard`, `command-guard`, `post-edit-validate`. Missing entries default to enabled. Wave-scope.json gains optional `gates` field; `gate_enabled()` in hardening.sh drives skip logic.
-- **Actionable suggestions in hook denials** (GL#78) — `enforce-scope.sh` and `enforce-commands.sh` now include a context-aware suggestion in their denial reason (e.g., force-push denial points to `--force-with-lease`; scope violation lists the allowed paths and next steps).
-- **STATE:/PLAN: structured reasoning** (GL#79) — new `reasoning-output` Session Config field (boolean, default `false`). When enabled, wave-executor appends a STATE/PLAN transparency block to every agent prompt. Opt-in — adds prompt overhead.
-- **Stagnation patterns** (GL#80) — `circuit-breaker.md` documents three new pagination-aware patterns (Pagination Spiral, Turn-Key Repetition, Error Echo) with a decision table mapping each to a recovery action. `wave-loop.md` step 2 hooks the per-agent check into the existing post-wave review. Detection is heuristic (LLM-applied), not executable code. Detection discipline explicitly notes that two different agents reading the same file is coordination, not stagnation.
-- **File-level grounding verification** (GL#81) — `plan-verification.md` § 1.1a compares planned files (union of agent prompt scopes) against actual files (`git diff --name-only $SESSION_START_REF..HEAD`) and reports scope creep + incomplete coverage. Adds a `grounding` field to session metrics JSONL. Gated by the new `grounding-check` Session Config field (boolean, default `true`). Informational only — does not block session close. `wave-loop.md` step 2 also gains a per-wave variant (bullet 3b) using each wave's pre-dispatch HEAD snapshot.
-- **Stagnation telemetry + error-echo classification** (GL#84) — `session-end` now emits per-agent stagnation events to `events.jsonl` with `pattern` + `error_class` fields; `evolve` accumulates these into `stagnation-class-frequency` learnings. `circuit-breaker.md` adds an Error-Class Taxonomy (scope-denied, command-denied, edit-format-friction, test-reality-gap, state-read-failure, unknown) with worked examples.
-- **Design Philosophy section in wave-executor** (GL#82) — 200-word framing between Execution Model and Platform Note explaining why friction is intentional; references `circuit-breaker.md` + `wave-loop.md`.
-- **Stagnation-class-frequency learning type** (GL#83) — shipped in `skills/evolve/SKILL.md:103-110` (redundant with #84 telemetry; issue closed as already-implemented in b238135).
-- **test-stagnation.sh** + **test-grounding.sh** — 27 new assertions covering content structure of the new sections, parse-config round-trip for `grounding-check`, error-path for invalid values, and structural ordering (1.1 < 1.1a < 1.2).
-- **vault-mirror skipped-invalid action** — new action type emitted when a JSONL entry fails field validation (C2 hardening); prevents silent data loss during auto-sync to the Meta-Vault.
-- **daily skill corrupt-file guard** — detects 0-byte or frontmatter-less daily notes and re-creates them; distinct exit codes 2/3/4 for file-missing / corrupt / frontmatter-invalid.
-
-### Changed
-- `hooks/enforce-scope.sh`, `hooks/enforce-commands.sh`, `hooks/post-edit-validate.sh` refactored to source `scripts/lib/hardening.sh`. Behavior is unchanged in the default configuration; new behavior surfaces only when `enforcement-gates` or `reasoning-output` are set.
-- `scripts/validate-wave-scope.sh` now validates the optional `gates` field (must be an object of booleans).
-- `scripts/parse-config.sh` adds `enforcement-gates`, `reasoning-output`, and `grounding-check` fields; `json_bool_object()` helper coerces string values to real JSON booleans.
-- `docs/session-config-reference.md` documents the new fields in the Persistence & Safety section.
-- `.mcp.json` now falls back to `git rev-parse --show-toplevel` when `$CLAUDE_PLUGIN_ROOT` is unset, allowing local development inside this repo to connect the MCP server without reinstalling as a plugin.
-- `skills/vault-sync/SKILL.md` — Outputs/Inputs sections rewritten to match `validator.mjs` impl; vestigial `--json` flag removed from `validator.sh`.
-- `skills/daily/SKILL.md` — documented VAULT_DIR Session Config resolution; added Exit codes table.
-- `skills/wave-executor/SKILL.md` — added Design Philosophy section (200w) with harness-friction framing.
-
-### Fixed
-- **vault-mirror C2 field validation** — malformed JSONL lines now produce `skipped-invalid` actions instead of crashing the sync loop.
-- **vault-mirror C3 readline race** — switched to `for await` collect-then-sequential to prevent out-of-order Markdown writes on large JSONL streams.
-- **vault-mirror C4 dry-run mkdir** — removed unconditional `mkdirSync` that leaked directories during `--dry-run`; guarded behind write-mode.
-- **vault-mirror H3/H4** — nested null-checks + `session_id` slug validation with uuid fallback.
-- **session-end C1 broken jq selector** — `.dest` / `written` action selector never matched; corrected to `.path` / `created|updated`. Action list extended with `skipped-invalid`.
-- **daily skill** — 0-byte and frontmatter-less daily notes now re-create cleanly instead of propagating corrupt state.
-
-### Sanitized
-- Public-surface cleanup: `skills/vault-sync/SKILL.md` and `skills/_shared/model-selection.md` no longer reference private project names or absolute user paths.
-- `.orchestrator/metrics/*.jsonl` removed from git tracking (per-project observability data belongs locally, not in the public repo).
-- `docs/specs/` removed from git tracking (internal design artifacts).
-- `.gitignore` updated accordingly.
-
-### Tests
-- 328 → 396 passing (33 new in test-hardening.sh, 6 new in test-parse-config.sh, 15 new in test-stagnation.sh, 12 new in test-grounding.sh — including 3 invalid-value error-path assertions, +2 in test-parse-config.sh for `grounding-check`).
-- Bats: `daily.bats` 8 → 10, `vault-mirror.bats` 36 → 40 (+6 assertions across the vault stack).
-
-## [2.0.0-beta.1] - 2026-04-08 — Beta Release
-
-### Added
-- **Clank Event Bus integration** (GL#53) — `scripts/lib/events.sh` with `so_emit_event()` function for async event emission to Clank's Event Bus (`events.<internal-host>/api/events`). Bearer-auth via `CLANK_EVENT_SECRET`, graceful degradation when unconfigured.
-- **SessionStart event hook** — `hooks/on-session-start.sh` emits `orchestrator.session.started` with platform and project context
-- **Stop/SubagentStop event emission** — existing hooks now emit `orchestrator.session.stopped` and `orchestrator.agent.stopped` events
-- **Output Styles** (GL#56) — 3 output style definitions (`output-styles/session-report.md`, `wave-summary.md`, `finding-report.md`) for consistent session reporting format
-- **test-events.sh** — 12 assertions covering event library loading, graceful degradation, hook integration, and registration
-
-### Changed
-- hooks.json + hooks-codex.json: SessionStart now includes async event notification hook
-- Plugin version: alpha.15 → beta.1
-- Tests: 172+ → 184+ passing (12 new event bus assertions)
-
-### Closed
-- GL#53 (HTTP Hooks — reimplemented as Clank Event Bus integration)
-- GL#56 (Output Styles)
-- GL#47 (Epic: Plugin API Alignment — all sub-issues resolved)
-
-## [2.0.0-alpha.15] - 2026-04-08 — Plugin API Alignment
-
-### Added
-- **plugin.json component paths** — `commands`, `agents`, `hooks`, `mcpServers` fields per Plugin API spec
-- **validate-plugin.sh** (GL#48) — 18-check validation script: manifest schema, component path resolution, hooks JSON, agent frontmatter, mcpServers validity
-- **test-validate-plugin.sh** — 17 assertions covering valid plugin, missing fields, invalid JSON, broken paths, bad frontmatter
-- **Stop hook** (GL#52) — `hooks/on-stop.sh` persists session state to metrics on unexpected exit
-- **SubagentStop hook** (GL#52) — `hooks/on-subagent-stop.sh` logs agent completion for wave-executor metrics
-- **MCP Server skeleton** (GL#54) — `.mcp.json` + `scripts/mcp-server.sh` exposing `session_config` and `session_metrics` tools via JSON-RPC 2.0 stdio
-
-### Changed
-- **Issue triage** (GL#60) — verified all 14 epic issues against actual Plugin API docs: 6 closed (not in API), 2 deferred, 4 implemented, 1 epic tracking
-- hooks.json + hooks-codex.json now include `Stop` and `SubagentStop` event types
-- Tests: 155 → 172+ passing (17 new validate-plugin assertions)
-
-### Closed (not in Plugin API)
-- GL#49 (`userConfig`), GL#50 (`CLAUDE_PLUGIN_DATA`), GL#51 (agent extended frontmatter), GL#55 (`bin/` auto-PATH), GL#57 (skill `paths`), GL#58 (LLM hook types)
-
-### Deferred
-- GL#53 (HTTP hooks), GL#56 (output styles)
-
-## [2.0.0-alpha.14] - 2026-04-07 — Cross-Platform + Housekeeping
-
-### Added
-- **Codex CLI full support** — platform detection (`scripts/lib/platform.sh`), `.orchestrator/metrics/` shared knowledge layer, `.codex-plugin/` with 3 agent TOMLs (explorer, wave-worker, session-reviewer), hooks-codex.json, codex-setup.md
-- **Cursor IDE rules-based integration** — 9 `.cursor/rules/*.mdc` files, sequential execution model (no Agent() tool), platform.sh cursor detection, cursor-setup.md, hooks-cursor.json, cursor-install.sh
-- **Intelligent agent dispatch** — 3-tier resolution: project agents > plugin agents > general-purpose fallback. 5 domain agents (code-implementer, test-writer, db-specialist, ui-developer, security-reviewer)
-- **Worktree tests** (GL#39) — `scripts/test/test-worktree.sh` with 10 assertions covering create/cleanup/cleanup_all
-- **Platform slow-path tests** (GL#42) — 8 assertions for marker directory detection without env vars
-
-### Changed
-- **DRY hook scripts** (GL#41) — all 3 hooks now source `platform.sh` instead of duplicating `find_project_root()`
-- **Removed orphan config fields** (GL#40) — `session-types` and `cli-tools` removed from parser, docs, tests, and 23 files total
-- **Codex agent specialization** documented as known limitation (GL#43) — Platform Limitations section in codex-setup.md
-- **Test-writer hardening** — 3 anti-greenwashing rules: hardcoded assertions, mandatory error tests, falsification self-check
-- **Lifecycle Simulation v3** — 37 gaps found across 3-platform trace, 28 fixed (session-end, wave-executor, session-plan, discovery, evolve, hooks, .cursor/rules)
-- All 10 SKILL.md files now include `model-preference-cursor` frontmatter
-- `skills/_shared/platform-tools.md` extended with Cursor column
-- `skills/_shared/config-reading.md` updated with Cursor fallback paths
-- Tests: 130 → 155 passing (10 worktree + 8 platform slow-path + adjustments for removed fields)
-
-### Fixed
-- **3 discovery issues created** — GL#44 (post-edit-validate.sh JSON injection), GL#45 (Session Config dogfooding), GL#46 (.claudeignore)
-
-## [2.0.0-alpha.13] - 2026-04-06 — Validate Refactor + Probes Split + PostToolUse Hook
-
-- **refactor:** extract 4 helpers from `validate()` in validate-wave-scope.sh — 109→22 lines (#25)
-- **refactor:** split `probes.md` (943 lines) into 6 category files — code, infra, ui, arch, session + intro (#26)
-- **feat:** PostToolUse hook for incremental typecheck after Edit/Write — informational, never blocks (#20)
-  - `hooks/post-edit-validate.sh` — resolves typecheck command from config, 2s timeout, macOS-compatible
-  - hooks.json updated with PostToolUse section
-- **test:** 33 new test assertions (wave-scope edge cases + hook test suite)
-- **fix:** macOS `date +%s%3N` compatibility in post-edit-validate.sh (BSD date lacks `%N`)
-
-## [2.0.0-alpha.12] - 2026-04-06 — /evolve + Skill Splits
-
-- **feat:** `/evolve` command + skill — extract, review, and list cross-session learnings (#21)
-  - `analyze` mode: extract patterns from session history (5 learning types), present via AskUserQuestion, atomic write
-  - `review` mode: interactive management (boost/reduce/delete/extend) of existing learnings
-  - `list` mode: read-only display grouped by type with confidence and expiry summary
-- **refactor:** extract `verification-checklist.md` from session-end SKILL.md Phase 2 (#18)
-- **refactor:** extract `wave-template.md` from session-plan SKILL.md Step 4 (#18)
-- **feat:** seed initial `learnings.jsonl` with 4 learnings from 8-session history (effective-sizing, scope-guidance)
-
-## [2.0.0-alpha.11] - 2026-04-06 — Deterministic Scripts
-
-- **feat:** `scripts/parse-config.sh` — deterministic Session Config parser with type validation, 36 fields, defaults from reference doc (#19)
-- **feat:** `scripts/run-quality-gate.sh` — 4 quality gate variants (baseline, incremental, full-gate, per-file) with structured JSON output (#19)
-- **feat:** `scripts/validate-wave-scope.sh` — wave-scope.json validator with security checks (path traversal, absolute paths) (#19)
-- **feat:** `scripts/lib/common.sh` — shared library (find_project_root, require_jq, die, warn, resolve_plugin_root)
-- **feat:** 94 bash tests across 3 test suites with 8 fixtures
-- **refactor:** skills updated to reference scripts (session-start, discovery, plan, wave-executor, session-end, quality-gates)
-
-## [2.0.0-alpha.10] - 2026-04-05
-
-### v2.0.0-alpha.10
-
-**Quality & Architecture**
-
-- fix: remove hardcoded archetype/style/group mappings in plan mode-new — now discovered dynamically from `$BASELINE_PATH` (#11)
-- feat: shared Session Config reference at `docs/session-config-reference.md` — single source of truth for all 36 fields (#12)
-- refactor: deduplicate Phase 0 config lists across session-start, discovery, and plan skills (#12)
-- refactor: extract session-start Phase 7 presentation template to `presentation-format.md` (#18)
-- refactor: session-start SKILL.md reduced from 290 to 210 lines (28% reduction) (#18)
-
-## [2.0.0-alpha.9] - 2026-04-05 — Cross-Repo Learnings + Competitive Analysis
-
-- **feat:** cross-repo learnings — anti-pattern detection, skill metadata extraction, confidence-based filtering
-- **feat:** skill frontmatter extended with `tags` and `model-preference` fields
-- **fix:** discovery probe consistency fixes (false positive reduction, deduplication logic)
-- **analysis:** competitive analysis of everything-claude-code, projects-baseline, claude-code-skills repos
-
-## [2.0.0-alpha.8] - 2026-04-04
-
-### Fixed
-- **enforce-scope.sh**: default enforcement changed from `warn` (fail-open) to `strict` (fail-closed) when `enforcement` field missing from `wave-scope.json`
-- **enforce-commands.sh**: same fail-closed default applied
-- **enforce-scope.sh**: incomplete regex metacharacter escaping — `+`, `?`, `|`, `[`, `]`, `(`, `)` now escaped before glob→regex conversion
-- **enforce-scope.sh**: symlink bypass — `realpath` canonicalization added for both PROJECT_ROOT and FILE_PATH (directory-level resolution for new files)
-- **enforce-commands.sh**: hardcoded fallback safety blocklist (`rm -rf`, `git push --force`, `git reset --hard`, `DROP TABLE`, `git checkout -- .`) enforced when `blockedCommands` absent from `wave-scope.json`
-- **Both hooks**: `CLAUDE_PROJECT_DIR` environment variable now validated — must contain `.claude/` directory to be trusted
-- **wave-executor**: jq prerequisite check added to Pre-Execution phase (step 4) — warns user if jq missing before wave dispatch
-
-### Changed
-- Plugin version alpha.7 → alpha.8
-- SECURITY.md expanded with Enforcement Architecture, Prerequisites, Known Limitations, Credential Safety sections
-- README.md: jq listed as prerequisite for enforcement hooks
-- USER-GUIDE.md: credential safety warning added to Session Config section
-
-## [2.0.0-alpha.7] - 2026-04-04
-
-### Added
-- **`/plan` skill** — structured project planning & PRD generation (#27)
-- `/plan new` — project kickoff with 3-wave requirement gathering, full PRD, and repo setup
-- `/plan feature` — compact feature PRD with 1-2 wave discovery
-- `/plan retro` — data-driven retrospective from session metrics
-- 3 PRD templates: full (8 sections), feature (5 sections), retro (metrics + actions)
-- PRD reviewer prompt with 6-criteria quality review and max 3 iteration protocol
-- Product Strategist soul identity (`skills/plan/soul.md`)
-- 4 new Session Config fields: `plan-baseline-path`, `plan-default-visibility`, `plan-prd-location`, `plan-retro-location`
-
-### Changed
-- Plugin version alpha.6 → alpha.7
-- SessionStart hook message updated to include `/plan [new|feature|retro]`
-- Component counts updated: 8→9 skills, 4→5 commands
-
-## [2.0.0-alpha.6] - 2026-04-04
-
-### Fixed
-- **Worktree enforcement bypass** — `find_project_root()` fallback added to both hook scripts (#21 prep)
-- **Quality wave scope conflict** — two-phase scope enforcement: simplification agents get production file scope, then test/review agents get test-only scope (#21 prep)
-- **Undefined `<session-start-ref>`** — `SESSION_START_REF` captured at session start, used in 3 locations (#21 prep)
-- **PARTIAL/SPIRAL/FAILED detection** — STATUS reporting protocol with coordinator detection rules and definitions table (#21 prep)
-- **Discovery embedded mode return contract** — JSON schema for findings + stats between discovery and session-end (#21 prep)
-- **Learnings I/O** — in-memory tracking in Phase 3.5a, atomic rewrite in Phase 3.6, explicit conditions (#21 prep)
-- 8 medium/low consistency fixes: subject matching, cross-module scope definition, sort order, gate headers, field naming, enforcement docs (M1-M6, L1-L2)
-
-### Changed
-- Version bumped alpha.5 → alpha.6 across 5 files
-- Validation checklist expanded from 11 to 17 scenarios
-
-## [2.0.0-alpha.5] - 2026-04-03
-
-### Added
-- **Confidence-based scoring for discovery probes** (#22) — 0-100 confidence score per finding based on pattern specificity, file context, and historical signal. Auto-defers low-confidence findings below configurable threshold (`discovery-confidence-threshold`, default: 60). Critical findings never auto-deferred.
-- **Post-implementation simplification pass** (#23) — Quality wave now dispatches simplification agents before test writers, applying `slop-patterns.md` patterns to clean AI-generated code (unnecessary try-catch, over-documentation, redundant boolean logic, re-implemented stdlib functions).
-- **Session-reviewer specialized review sections** (#24) — 3 new review sections: Silent Failure Analysis (catch blocks that swallow errors), Test Depth Check (assertion quality, mock boundaries), Type Design Spot-Check (overly broad types, missing unions). Per-finding confidence scoring (>=80 threshold).
-- **CLAUDE.md quality audit probe** (#25) — New `claude-md-audit` probe in session category: validates Session Config paths, checks rules freshness against codebase, detects stale CLAUDE.md, cross-references technology mentions against package.json.
-- **Session effectiveness tracking** (#26) — Extended `sessions.jsonl` schema with `discovery_stats`, `review_stats`, and `effectiveness` fields. Session-start surfaces completion rate trends, low-value probe detection, and carryover pattern analysis after 5+ sessions.
-- Confidence Scoring Reference section in `probes.md` with per-category guidance
-- Discovery Phase 6 (Capture Discovery Stats) for standalone mode
-
-## [2.0.0-alpha.4] - 2026-04-03
-
-### Fixed
-- **enforce-scope.sh**: glob matching now supports `**` recursive patterns via regex conversion (was limited to single-level globs)
-- **enforce-commands.sh**: word-boundary matching prevents false positives (e.g., `rm -rflag` no longer blocked by `rm -rf` pattern)
-- **session_id uniqueness**: format changed from `<branch>-<YYYY-MM-DD>` to `<branch>-<YYYY-MM-DD>-<HHmm>` to prevent same-day collisions
-- **Spiral detection scope**: clarified as per-agent (not per-wave) — two agents editing the same file is expected, not a spiral
-- **Complexity tier boundaries**: rebalanced to Simple (0-1), Moderate (2-3), Complex (4-6) for better distribution
-- **Dynamic scaling threshold**: "fast" defined as under 3 minutes wall-clock (was undefined)
-- **Worktree merge strategy**: defined sequential merge protocol with conflict resolution heuristics
-- **Directory creation**: explicit `mkdir -p` commands instead of prose instructions for STATE.md and metrics
-- **JSONL write safety**: documented POSIX-atomic `>>` append, warned against read-modify-write
-- **USER-GUIDE spiral wording**: corrected "per wave" to "per agent" to match authoritative circuit-breaker.md
-
-### Added
-- `deviation-pattern` learning type — session-end now reads STATE.md deviations for cross-session pattern extraction
-- Discovery role enforcement: `allowedPaths: []` + read-only prompt instruction
-- Quality role scope restriction: `allowedPaths` limited to test file patterns (`**/*.test.*`, `**/*.spec.*`, `**/__tests__/**`)
-- Role combination verification example (Discovery+Impl-Core → Incremental checks)
-- 6+ wave splitting criteria (by module/dependency boundary)
-- jq prerequisite documentation in USER-GUIDE.md with install commands
-- Integration test reference config (`docs/examples/integration-test-config.md`) covering all 30 Session Config fields
-- Validation checklist (`docs/validation-checklist.md`) mapping to #21's 11 test plan items
-
-### Changed
-- Hook jq-missing warnings now explicitly state that enforcement is fully disabled
-- `enforce-scope.sh` matching has 4 branches: directory prefix → recursive glob → simple glob → exact match
-
-## [2.0.0-alpha.3] - 2026-04-03
-
-### Added
-- Session metrics tracking — wall-clock time, agent counts, files changed per wave (#8)
-- Historical trend display in session-start showing last 5 sessions
-- Adaptive wave sizing with complexity scoring (simple/moderate/complex tiers) (#19)
-- Dynamic agent scaling between waves based on performance signals
-- Cross-session learning system with confidence scoring (#20)
-- Project Intelligence sections in session-start and session-plan from accumulated learnings
-- Structured quality-gates output format (JSON) for metrics integration
-
-### Changed
-- Circuit breaker and worktree isolation extracted to `circuit-breaker.md` sub-reference
-- session-plan steps renumbered (new Step 3: Complexity Assessment)
-- session-end Final Report expanded with per-wave metrics breakdown and learnings summary
-- Quality gates Variants 2 and 3 have structured JSON output specifications
-
-## [2.0.0-alpha.2] - 2026-04-03
-
-### Added
-- Hybrid session persistence via STATE.md lifecycle (init/update/clear) + session memory files (#16)
-- PreToolUse hook enforcement: enforce-scope.sh (Edit/Write), enforce-commands.sh (Bash) (#17)
-- Circuit breaker with maxTurns limit and spiral detection (#18)
-- Worktree isolation for parallel agent execution (#18)
-- 5 new Session Config fields: persistence, memory-cleanup-threshold, enforcement, isolation, max-turns
-- SESSION-START Phase 0.5 (Session Continuity) and Phase 5.5 (Memory Recall)
-
-### Changed
-- USER-GUIDE.md: 2 new sections (Session Persistence, Safety Features) + config fields + cheat sheet
-- wave-executor: STATE.md initialization, post-wave updates, scope manifest, circuit breaker
-
-## [2.0.0-alpha] - 2026-04-02
-
-### Added
-- quality-gates reference skill — canonical commands for typecheck, test, lint with 4 variants (Baseline, Incremental, Full Gate, Per-File)
-- 9 new Session Config fields: test-command, typecheck-command, lint-command, ssot-freshness-days, plugin-freshness-days, recent-commits, issue-limit, stale-branch-days, stale-issue-days
-- Role-to-wave mapping table — waves dynamically map to 5 roles (Discovery, Impl-Core, Impl-Polish, Quality, Finalization) based on configured wave count (3-6+)
-- discovery skill with /discovery command — systematic quality audit with 22 probes across 5 categories (code, infra, ui, arch, session)
-- 4 new Session Config fields for discovery: discovery-on-close, discovery-probes, discovery-exclude-paths, discovery-severity-threshold
+---
 
-### Changed
-- gitlab-ops is now the single source of truth for all VCS operations — consuming skills reference it instead of duplicating commands (#11)
-- Quality checks across all skills now reference quality-gates instead of hardcoding commands (#12)
-- Session Config documentation consolidated — USER-GUIDE.md Section 4 is the authoritative field reference (#13)
-- All hardcoded thresholds (SSOT freshness, plugin age, stale branches, etc.) are now configurable via Session Config (#14)
-- Wave execution model rewritten from hardcoded wave numbers to role-based assignment (#15)
-- Pencil design review triggers now reference Impl-Core and Impl-Polish roles instead of Wave 2/3
-- Label taxonomy in CONTRIBUTING.md and USER-GUIDE.md now points to gitlab-ops as SSOT
+## Older versions
 
-### Removed
-- ~80 lines of duplicated VCS detection/command logic across 4 skills
-- ~30 lines of duplicated quality check commands across 4 skills
-- ~60 lines of duplicated Session Config documentation across 3 files
-- All hardcoded "Wave 1/2/3/4/5" references in favor of role names
+To keep this file focused on the current **3.x** major line, changelog entries for the
+earlier release lines have been archived:
 
-## [1.0.0] - 2026-04-02
-
-### Added
-- 6 skills: session-start, session-plan, wave-executor, session-end, ecosystem-health, gitlab-ops
-- 3 commands: /session, /go, /close
-- 1 agent: session-reviewer (inter-wave quality gate)
-- SessionStart hook with startup notification
-- Soul personality system (soul.md)
-- VCS auto-detection with dual GitLab + GitHub support
-- 5-wave execution pattern with configurable agent counts
-- Inter-wave Pencil design-code alignment reviews
-- Ecosystem health monitoring (service endpoints + cross-repo scanning)
-- Session Config system with 13 configurable fields
-- User Guide, CONTRIBUTING guide, and example Session Configs
+- [`docs/changelog/v2.md`](docs/changelog/v2.md) — the **2.x** line (2.0.0 and its alpha/beta pre-releases, 2026-04-02 -> 2026-04-17)
+- [`docs/changelog/v1.md`](docs/changelog/v1.md) — the **1.x** line (1.0.0, 2026-04-02)