@jagilber-org/index-server 1.19.1

package/CHANGELOG.md

@@ -0,0 +1,1218 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on Keep a Changelog and this project adheres to Semantic Versioning.
+
+## [1.19.0] - 2026-04-10
+
+### Changed
+
+- **Environment variable consolidation** — All direct `process.env` reads in runtime source files have been migrated to the centralized `getRuntimeConfig()` config layer. 12 files consolidated: `handlers.feedback.ts`, `autoBackup.ts`, `instructions.dispatcher.ts`, `sqlite.routes.ts`, `admin.routes.ts`, `seedBootstrap.ts`, `sdkServer.ts`, `BufferRing.ts`, `SessionPersistenceManager.ts`, `manifestManager.ts`, `registry.ts`, `transportFactory.ts`.
+- **Standardized env var prefixes** — Unprefixed environment variables have been replaced with `INDEX_SERVER_*` equivalents. Old unprefixed names are no longer supported.
+
+### Environment Variables
+
+- `INDEX_SERVER_BUFFER_RING_APPEND` — replaces `BUFFER_RING_APPEND` (default: `1`)
+- `INDEX_SERVER_BUFFER_RING_PRELOAD` — replaces `BUFFER_RING_APPEND_PRELOAD` (default: `0`)
+- `INDEX_SERVER_GRAPH_INCLUDE_PRIMARY_EDGES` — replaces `GRAPH_INCLUDE_PRIMARY_EDGES` (default: `1`)
+- `INDEX_SERVER_GRAPH_LARGE_CATEGORY_CAP` — replaces `GRAPH_LARGE_CATEGORY_CAP` (default: `150`)
+- `INDEX_SERVER_AUDIT_LOG` — replaces `INSTRUCTIONS_AUDIT_LOG` (default: enabled, `logs/audit/`)
+- `INDEX_SERVER_COVERAGE_FAST` — replaces `FAST_COVERAGE` (default: `0`)
+- `INDEX_SERVER_COVERAGE_HARD_MIN` — replaces `COVERAGE_HARD_MIN`
+- `INDEX_SERVER_COVERAGE_TARGET` — replaces `COVERAGE_TARGET`
+- `INDEX_SERVER_COVERAGE_STRICT` — replaces `COVERAGE_STRICT` (default: `0`)
+
+### Fixed
+
+- Pre-commit hooks and publish scripts hardened against env-var leaks (SHA-256 token validation)
+- `.gitignore` negation pattern (`!instructions/*.json`) removed to prevent instruction file leakage
+
+## [1.18.0] - 2026-04-06
+
+### Added
+
+- **SQLite storage backend** (⚠️ EXPERIMENTAL — limited testing performed): `INDEX_SERVER_STORAGE_BACKEND=sqlite` enables SQLite-backed instruction storage using Node.js built-in `node:sqlite` (zero third-party dependencies). Not recommended for production use.
+  - `IInstructionStore` interface — storage abstraction layer for backend-agnostic instruction persistence
+  - `JsonFileStore` — existing JSON-file-per-instruction behavior wrapped in the interface
+  - `SqliteStore` — full SQLite implementation with WAL mode, indexes, and FTS5 full-text search
+  - `SqliteMessageStore` — message persistence in SQLite with channel/sender/thread queries
+  - `SqliteUsageStore` — usage tracking in SQLite with atomic increment
+  - Migration engine — bidirectional JSON ↔ SQLite migration (lossless round-trip)
+  - FTS5 search with BM25 ranking (title 10x, body 5x weight)
+  - SQLite backup support in autoBackup (copies .db + WAL/SHM files)
+  - Factory pattern with feature flag: `createStore()` selects backend from config
+  - 115+ storage-specific tests (contract, migration, FTS5, messaging, usage)
+  - Governance hash identical across both backends
+- **NDJSON structured logging**: All server log output now uses strict NDJSON (newline-delimited JSON) format. Each log line is a JSON object with `ts`, `level`, `msg`, and optional `detail`, `tool`, `ms`, `pid`, `port`, `correlationId` fields. V8 `Error.captureStackTrace` auto-populates stack traces on WARN/ERROR. Module-prefixed messages (`[module]`) support source-file heatmap matching.
+- **Markdown preview in instruction editor**: Dashboard instruction editor includes a 📖 Preview button that renders the instruction `body` as GitHub Flavored Markdown (via `marked`). Preview auto-updates as you type.
+- **Zip-based backups**: All backup operations (auto-backup, bulk-delete, admin panel) now produce `.zip` archives via `adm-zip`. SQLite backend backups include WAL/SHM files for full state preservation. Retention pruning removes oldest snapshots beyond `INDEX_SERVER_AUTO_BACKUP_MAX_COUNT`.
+- **Offset/limit pagination** for `index_dispatch` list action.
+
+### Changed
+
+- **Pre-push slow test gate removed** — slow tests now run exclusively in CI workflows.
+- Security headers added to dashboard script routes.
+- Large modules split into focused single-responsibility files (CQ-1 compliance).
+- 66 ESLint unused-variable warnings resolved.
+
+### Environment Variables (⚠️ SQLite options are experimental)
+
+- `INDEX_SERVER_STORAGE_BACKEND` — `json` (default) or `sqlite` (experimental — not recommended for production)
+- `INDEX_SERVER_SQLITE_PATH` — SQLite database path (default: `data/index.db`)
+- `INDEX_SERVER_SQLITE_WAL` — Enable WAL mode (default: `true`)
+- `INDEX_SERVER_SQLITE_MIGRATE_ON_START` — Auto-migrate JSON → SQLite on first start (default: `true`)
+
+## [1.16.1] - 2026-04-01
+
+### Fixed
+
+- **VSIX extension**: Renamed all "Catalog" references to "Index"/"Index Server" in extension UI (commands, walkthrough, settings, README, icon).
+
+### Added
+
+- **Azure DevOps pipeline**: `azure-pipelines.yml` for private VSIX publishing via ADO.
+
+## [1.16.0] - 2026-04-01
+
+### Added
+
+- **Signal feedback loop**: `index_groom` reads usage signals from `usage_track` and mutates instructions: `outdated` -> deprecated, `not-relevant` -> priority -10, `helpful` -> priority +5, `applied` -> priority +2.
+- **Dashboard signal visibility**: Instructions panel shows USES/SIGNAL chips per instruction with sort options. Overview panel shows usage signal summary card. Maintenance panel has signal groom controls.
+- **REST client scripts**: `scripts/index-server-client.ps1` (PowerShell) and `scripts/index-server-client.sh` (bash) for subagents without MCP tool access. Full CRUD via dashboard REST bridge.
+- **Incremental embedding cache**: Semantic search recomputes only changed entries instead of full catalog on any modification.
+- **Embedding concurrency lock**: Concurrent cache-miss searches share one in-flight computation instead of tripling work.
+- **HSTS header**: `Strict-Transport-Security` added when TLS is enabled.
+- **Usage snapshot API**: `GET /api/usage/snapshot` dashboard route for per-instruction signal data.
+- **`usage_hotset` signals**: Items now include `lastSignal` and `lastComment` from usage snapshot.
+
+### Changed
+
+- **BREAKING: `index_groom` output schema**: `usagePruned` replaced by `signalApplied`. Added `migrated` and `remappedCategories` fields.
+- **`loadUsageSnapshot` exported**: Now available for import from `catalogContext.ts`.
+- **Usage snapshot path configurable**: `INDEX_SERVER_USAGE_SNAPSHOT_PATH` env var for test isolation.
+
+## [1.15.2] - 2026-04-01
+
+### Fixed
+
+- **Codecov workflow**: Corrected CI workflow configuration for Codecov coverage uploads.
+- **Dashboard inline scripts**: `safeExecInlineCode` now passes original arguments instead of Event object.
+
+### Changed
+
+- **README**: Replaced with trimmed, focused version.
+
+## [1.14.0] - 2026-03-29
+
+### Changed
+
+- **BREAKING: Tool names renamed** from `instructions_*` to `index_*` across the entire codebase. Affected tools: `index_dispatch`, `index_search`, `index_add`, `index_import`, `index_remove`, `index_reload`, `index_repair`, `index_groom`, `index_enrich`, `index_normalize`, `index_governanceHash`, `index_governanceUpdate`, `index_schema`, `index_health`, `index_inspect`, `index_diagnostics`, `index_debugCatalog`.
+- **BREAKING: Environment variables renamed** from `MCP_*` prefix to `INDEX_SERVER_*`. Key renames: `MCP_INSTRUCTIONS_DIR` -> `INDEX_SERVER_DIR`, `MCP_ENABLE_MUTATION` -> `INDEX_SERVER_MUTATION`, `MCP_LOG_VERBOSE` -> `INDEX_SERVER_VERBOSE_LOGGING`, `MCP_LOG_LEVEL` -> `INDEX_SERVER_LOG_LEVEL`, `MCP_DATA_DIR` -> `INDEX_SERVER_DATA_DIR`, `MCP_DASHBOARD_PORT` -> `INDEX_SERVER_DASHBOARD_PORT`, `MCP_DASHBOARD_TLS` -> `INDEX_SERVER_DASHBOARD_TLS`, `MCP_SECRET_KEY` -> `INDEX_SERVER_SECRET_KEY`, `MCP_AUTH_KEY` -> `INDEX_SERVER_AUTH_KEY`, plus 8 more.
+- **Removed all legacy/fallback env var support**: No backward-compatible dual-read aliases. `warnOnce()` deprecation helper and `deprecationNotices` set removed from runtimeConfig.ts.
+- **100% Zod coverage**: All 45+ tools have complete Zod schemas in `toolRegistry.zod.ts` with strict validation.
+- **Instruction catalog content updated**: Renamed `mcp-index-server` -> `index-server` and all tool/env var references across 585+ production instruction files and 22 local instruction files via reusable `scripts/rename-server-in-instructions.ps1`.
+
+### Added
+
+- **Reusable rename script**: `scripts/rename-server-in-instructions.ps1` with mapping file support, WhatIf, backup/DR zip, JSON validation, manifest updates, and verification scan.
+- **Mapping files**: `scripts/mappings/index-server-rename.json` (35 replacement pairs), `scripts/mappings/server-env-tools.json` (auto-generated env var + tool name inventory).
+
+## [1.13.2] - 2026-03-29
+
+### Changed
+
+- **Renamed server entry point**: `dist/server/index.js` -> `dist/server/index-server.js` for clarity. Source file renamed from `src/server/index.ts` to `src/server/index-server.ts`. All scripts, CI workflows, configs, tests, and documentation updated (92+ files).
+- **Deploy script**: `scripts/deploy-local.ps1` updated -- generated `start.ps1`, `start.cmd`, and runtime `package.json` all reference the new entry point name.
+- **Shim scripts**: `ci-build.js`, `ci-build.mjs`, `pretest-build-or-skip.mjs/.ps1`, and `distReady.ts` updated to create/locate `index-server.js` instead of `index.js`.
+
+## [1.12.0] - 2026-03-16
+
+### Added
+
+- **Embeddings visualization panel**: New dashboard tab displaying embedding vectors, cosine similarity heatmaps, and cluster analysis for instruction catalog entries.
+- **Graph tab toggle** (`INDEX_SERVER_DASHBOARD_GRAPH`): Opt-in env var to enable the Graph visualization tab. When disabled (default), the server strips the graph nav button, section HTML, and `admin.graph.js` script tag from the dashboard -- avoiding ~4.5MB of mermaid + elkjs JS downloads.
+- **PPID watchdog**: Belt-and-suspenders orphan detection that checks every 30s if the parent process is still alive via `process.kill(ppid, 0)`. Exits gracefully if parent is gone, covering Windows edge cases where stdin EOF is unreliable.
+- **Bundled dashboard assets**: Chart.js 4.4.0, mermaid 11.11.0, and elkjs 0.9.3 are now served locally from `/js/` -- no external CDN calls in production.
+- **System font stack**: Replaced Google Fonts (Inter) with `system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif`.
+
+### Changed
+
+- **Semantic search defaults**: `INDEX_SERVER_SEMANTIC_LOCAL_ONLY` now defaults to `true` (blocks remote HuggingFace downloads). `INDEX_SERVER_SEMANTIC_ENABLED` defaults to `false`.
+- **CSP tightened**: Content-Security-Policy is now `'self'` only -- removed cdn.jsdelivr.net, unpkg.com, fonts.googleapis.com, fonts.gstatic.com.
+- **CDN versions pinned**: mermaid pinned to 11.11.0, ELK ESM to 0.2.0, elkjs to 0.9.3, diagram-viewer mermaid to 10.9.3.
+
+### Fixed
+
+- **Orphaned server processes**: Added stdin `end`/`close` handler that calls `shutdownGuard.initiateShutdown('stdin-closed')` + `process.exit()` when the parent (VS Code) disconnects. Prevents the Express dashboard HTTP server from keeping orphaned processes alive indefinitely.
+- **Embeddings panel Load button**: Fixed boot.js CSP sanitizer blocking `window.fn && window.fn()` inline onclick patterns.
+- **Mermaid graph CSP**: Relaxed then eliminated CSP CDN allowances by bundling all graph assets locally.
+- **ELK ESM chunks**: `copy-dashboard-assets.mjs` now copies the `chunks/` subdirectory required by the ELK ESM entry point.
+
+## [1.11.2] - 2026-03-12
+
+### Security
+
+- **CORS hardening**: Replaced permissive `Access-Control-Allow-Origin: *` with localhost-only origin validation in DashboardServer, ApiRoutes, and SSE log streaming.
+- **Security headers**: Added CSP, X-Frame-Options (DENY), X-Content-Type-Options, X-XSS-Protection, and Referrer-Policy to all dashboard HTTP responses.
+- **Admin authentication**: Added API key middleware (`INDEX_SERVER_ADMIN_API_KEY` env var) to all `/api/admin/*` routes with localhost-fallback for backward compatibility.
+- **Code injection fix**: Replaced `new Function()` usage in APIIntegration.ts with safe dot-path transform methods and type coercion allowlist.
+- **Inline handler fix**: Replaced `new Function()` in admin.boot.js with safe named-function dispatch via window object traversal.
+- **TOCTOU fix**: Replaced `existsSync()` + `readFileSync()` pattern in index_inspect with direct read + ENOENT error code check.
+
+### Fixed
+
+- **Shutdown race condition**: Consolidated multiple competing `process.exit()` calls (SIGINT, SIGTERM, uncaughtException across index.ts, transport.ts, catalogContext.ts) into single `ShutdownGuard` with re-entrance protection.
+- **Silent error swallowing**: Added structured error logging to critical catch blocks in autoBackup.ts (interval, initial run, pruning).
+
+### Added
+
+- **ShutdownGuard module** (`src/server/shutdownGuard.ts`): Singleton factory with named cleanup handler registry, re-entrance guard, and exit code mapping. 7 unit tests.
+- **Coverage thresholds**: Added branch (70%), function (70%), line (75%), statement (75%) thresholds to vitest.config.ts.
+- **Dependabot config**: Created `.github/dependabot.yml` for weekly npm and GitHub Actions dependency updates.
+- **CodeQL weekly scans**: Enabled Monday 3am UTC scheduled scan in `.github/workflows/codeql.yml`.
+- **CODEOWNERS expansion**: Added dashboard, server, workflows, and config paths to `.github/CODEOWNERS`.
+
+## [1.11.1] - 2026-03-04
+
+### Added
+
+- **Usage test coverage**: Replaced 4 placeholder usage test files with 11 real functional tests covering feature gating (`hasFeature`/`INDEX_SERVER_FEATURES`), usage tracking (`incrementUsage`), `firstSeenTs`/`lastUsedAt` timestamps, and rate-limit clearing.
+- **Dev MCP config**: Added `INDEX_SERVER_FLAG_TOOLS_EXTENDED=1` to workspace dev server config.
+
+### Changed
+
+- **Documentation**: Updated `INDEX_SERVER_FEATURES` env var description in `docs/tools.md` to list all valid feature flags (`usage,window,hotness,drift,risk`).
+
+## [1.11.0] - 2026-03-03
+
+### Added
+
+- **Dashboard configuration panel redesign**: Category-grouped flags with collapsible sections, live search/filter, documentation links (📖 icons), 15-second auto-refresh, stability color coding, and full-height layout replacing the constrained 480px scroll area.
+- **Constitution rule A-7**: Canonical seeds in `seedBootstrap.ts` must contain only generalized, public-safe content — no environment-specific or org-specific data.
+
+### Changed
+
+- **Auto-backup default**: `autoBackupEnabled` now defaults to `false` (was `true`). Set `INDEX_SERVER_AUTO_BACKUP=1` to re-enable.
+- **Flag registry sorting**: `/api/admin/config` flags are now sorted by category → name for consistent ordering.
+- **Flag metadata**: Each flag now includes a `docAnchor` slug and the response includes `lastRefreshed` timestamp.
+
+## [1.10.0] - 2026-03-02
+
+### Added
+
+- **Auto usage tracking**: Get and search operations now automatically track usage for retrieved instructions via fire-and-forget `incrementUsage` calls. Controlled by `INDEX_SERVER_AUTO_USAGE_TRACK` env var (default: `true`). Search tracks top 10 results; get tracks each successful retrieval.
+- **Embedding cache model awareness**: Embedding cache now stores `modelName` alongside `catalogHash`, automatically invalidating cached embeddings when the semantic model is changed (e.g., switching from `all-MiniLM-L6-v2` to `bge-base-en-v1.5`). Prevents dimension mismatch errors.
+- **Zod schema for `index_search`**: Added `zInstructionsSearch` to `toolRegistry.zod.ts` with all parameters (`keywords`, `mode`, `limit`, `includeCategories`, `caseSensitive`, `contentType`) matching the JSON Schema definition.
+- **Documentation**: Added docs index, MCP configuration guide, project PRD, prompt optimization guide, search benchmark results, credential centralization runbook.
+- **Benchmark script**: `scripts/benchmark-search.ps1` — stress-tests keyword/regex/semantic search modes and generates markdown + Mermaid report.
+- **Tools REST routes**: `src/dashboard/server/routes/tools.routes.ts` — REST bridge for MCP tool handlers.
+
+### Fixed
+
+- **Semantic test crash**: `autoTrackSearchResults()` and dispatcher auto-tracking now use optional chaining (`catalog?.autoUsageTrack`) to avoid `TypeError` when `catalog` config is undefined in test context.
+
+### Changed
+
+- **Upgraded recommended model**: Documentation and prod config updated for `Xenova/bge-base-en-v1.5` (768-dim, ~90MB) over default `Xenova/all-MiniLM-L6-v2` (384-dim), providing ~30% quality improvement for semantic search.
+
+## [1.9.0] - 2026-03-01
+
+### Added
+
+- **Search modes**: `index_search` now supports `mode` parameter with three values:
+  - `keyword` (default) — substring matching with auto-tokenization
+  - `regex` — pattern matching (e.g., `"deploy|release"`, `"Type[Ss]cript"`) with ReDoS protection (200-char limit)
+  - `semantic` — embedding-based cosine similarity search with lazy-loaded HuggingFace model, disk-cached embeddings, and graceful degradation to keyword mode on failure. Requires `INDEX_SERVER_SEMANTIC_ENABLED=1`.
+- **Embedding service**: New `embeddingService.ts` with cosine similarity, disk cache, staleness detection, and lazy model loading (zero startup impact).
+- **Semantic configuration**: New env vars `INDEX_SERVER_SEMANTIC_ENABLED`, `INDEX_SERVER_SEMANTIC_MODEL`, `INDEX_SERVER_SEMANTIC_CACHE_DIR`, `INDEX_SERVER_EMBEDDING_PATH`, `INDEX_SERVER_SEMANTIC_DEVICE`, `INDEX_SERVER_SEMANTIC_LOCAL_ONLY` via `SemanticConfig` in `runtimeConfig.ts`.
+  - `INDEX_SERVER_SEMANTIC_DEVICE` — Run embeddings on GPU: `cuda` (NVIDIA) or `dml` (DirectML/Windows). Default: `cpu`.
+  - `INDEX_SERVER_SEMANTIC_LOCAL_ONLY` — Block remote model downloads when set to `1`. Model must already be cached.
+- **Search highlighting**: Match highlighting in both global search results and local instruction list filter using `<mark>` tags with gold background.
+- **Backup file export/import**: "Backup to File" and "Restore from File" buttons in Maintenance tab with file dialog support.
+- **Server export/import endpoints**: `GET /api/admin/maintenance/backup/:id/export` and `POST /api/admin/maintenance/backup/import` for backup bundle transfer.
+- **Regex search toggle**: Checkbox to enable regex mode for instruction name filter and global search.
+
+### Fixed
+
+- **Global search URL mismatch**: Client was calling `/api/instructions/search` but server route is `/api/index_search` — global search always returned "Not found".
+- **Cache-busting**: Now hashes all JS + CSS + HTML files (was CSS-only), ensuring JS changes are picked up by browsers.
+- **Instance badge**: Shows green when count > 0 (was > 1).
+- **Instance dropdown positioning**: Aligned left instead of centered.
+- **Create instruction template**: Now populates with full v4 schema template instead of minimal stub.
+
+## [1.8.4] - 2026-02-27
+
+### Changed
+
+- **Dashboard Grafana-dark theme**: Complete CSS redesign with enterprise dark theme, vertical edge alignment, and graph loading skeleton fix.
+- **Dashboard documentation**: Added panel screenshots gallery to DASHBOARD.md and README.md covering all 7 tabs (Overview, Configuration, Sessions, Maintenance, Monitoring, Instructions, Graph).
+- **Default route**: Root `/` now redirects to `/admin` dashboard; legacy v1 available at `/legacy`.
+
+### Added
+
+- **Screenshot capture script**: `scripts/capture-screenshots.mjs` using Playwright for repeatable dashboard screenshot generation.
+
+## [1.8.3] - 2026-02-26
+
+### Added
+
+- **Automatic periodic backup**: New `autoBackup` service backs up the instruction catalog on a configurable interval (default 1 hour). Enabled by default (`INDEX_SERVER_AUTO_BACKUP=1`). Old snapshots are pruned to `INDEX_SERVER_AUTO_BACKUP_MAX_COUNT` (default 10). Startup is async and non-blocking via `setImmediate` with a 5-second first-run delay.
+
+### Fixed
+
+- **Version 0.0.0 in `createSdkServer`**: Server now resolves `package.json` from multiple candidate paths (`__dirname` fallbacks) instead of relying solely on `process.cwd()`, which VS Code sets to an unrelated directory.
+- **7 tools instead of 50**: Extended and admin tool tiers now activate correctly when `INDEX_SERVER_FLAG_TOOLS_EXTENDED=1` and `INDEX_SERVER_FLAG_TOOLS_ADMIN=1` are set in the MCP client configuration.
+
+## [1.8.2] - 2026-02-26
+
+### Added
+
+- **Bulk deletion safeguards**: `index_remove` now enforces a configurable threshold (`INDEX_SERVER_MAX_BULK_DELETE`, default 5). Requests exceeding the threshold are blocked unless `force: true` is passed.
+- **Pre-mutation auto-backup**: When a forced bulk delete exceeds the threshold and `INDEX_SERVER_BACKUP_BEFORE_BULK_DELETE` is enabled (default), all instruction files are snapshotted to `backups/instructions-{timestamp}/` before deletion proceeds. Backup failure aborts the entire operation.
+- **Dry-run mode**: `index_remove` accepts `dryRun: true` to preview which IDs would be deleted without modifying disk.
+- **New env vars**: `INDEX_SERVER_MAX_BULK_DELETE` (number, default 5), `INDEX_SERVER_BACKUP_BEFORE_BULK_DELETE` (boolean, default true).
+- **Tests**: `bulkDeleteGuard.spec.ts` — 6 unit tests covering threshold enforcement, force override, dry-run, and auto-backup behavior.
+
+### Security
+
+- Mitigates accidental or automated mass instruction deletion — the incident that wiped production catalog is no longer possible without explicit `force` acknowledgement and automatic backup.
+
+## [1.8.1] - 2026-02-24
+
+### Fixed
+
+- **Dispatcher flat-param assembly**: `index_dispatch` action=add now accepts flat params (`id`, `body`, `title` as top-level) in addition to the nested `entry` wrapper. Agents no longer need to pre-wrap instruction fields. Resolves feedback #0d4d73a6.
+- **Schema completeness**: Dispatch `INPUT_SCHEMA` now exposes all mutation-action params: `entry`, `overwrite`, `lax` (add), `entries`, `mode` (import/groom), `owner`, `status`, `bump`, `lastReviewedAt`, `nextReviewDue` (governanceUpdate), `missingOk` (remove).
+- **Build fix**: TS18046 in `feedbackDispatch.red.spec.ts` resolved (release v1.8.0 build failure).
+
+### Added
+
+- **Constitution Q-7**: Schema-contract tests required for dispatcher action additions.
+- **Constitution Q-8**: Agent-perspective tests required for mutation dispatch actions.
+- **Test file**: `dispatcherAddFlatParams.spec.ts` — 11 contract + agent-perspective tests covering all dispatch mutation actions.
+
+## [1.8.0] - 2026-02-24
+
+### Changed
+
+- **BREAKING: Tool surface reduced from 44 to 7 core tools**. Extended/admin tools available via `INDEX_SERVER_FLAG_TOOLS_EXTENDED` / `INDEX_SERVER_FLAG_TOOLS_ADMIN` feature flags.
+- **ToolTier system**: `core` / `extended` / `admin` tiers with `getToolRegistry(filter?)` tier-based filtering.
+- **Action-based dispatchers**:
+  - `feedback_dispatch`: consolidates 6 feedback tools into `submit`/`list`/`get`/`update`/`stats`/`health` actions
+  - `bootstrap`: consolidates 3 bootstrap tools into `request`/`status`/`confirm` actions
+  - `index_dispatch`: added `manifestStatus`/`manifestRefresh`/`manifestRepair` actions
+
+## [1.7.0] - 2026-02-17
+
+### Removed
+
+- **Portable MCP test client removed**: Deleted `portable/` and `portable-mcp-client/` directories, `portableClientShim.ts`, all portable type declarations, and 13 portable-specific test files. The vendored client was back-ported to its origin repo (`jagilber/mcp-client`) before removal.
+- **Portable environment variables**: Removed `PORTABLE_HANDSHAKE_TRACE`, `PORTABLE_CONNECT_TRACE`, `PORTABLE_WAIT_ID_TIMEOUT_MS` legacy env vars from runtime config and test utilities.
+- **Parked tests**: Removed `src/tests._park/` directory containing obsoleted portable comparison/baseline specs.
+
+### Added
+
+- **SDK-based test client** (`src/tests/helpers/mcpTestClient.ts`): Lightweight replacement using `@modelcontextprotocol/sdk` directly. Provides `spawnServer()` (low-level MCP connect) and `createTestClient()` (high-level CRUD + `importBulk` + `governanceUpdate`).
+- **Copilot CLI E2E script** (`scripts/copilot-e2e.ps1`): E2E smoke test using GitHub Copilot CLI programmatic mode as the recommended interactive MCP client.
+
+### Changed
+
+- **Integration tests refactored**: All integration tests now use `mcpTestClient` instead of `portable-mcp-client`. Affected: `instructionsCreateAtomicVisibility`, `instructionsRemoveAtomicVisibility`, `instructionsPersistenceDivergence`, `instructionsPersistenceIsolated`, `instructionsExternalReload`, `instructionSchema`, `feedbackReproduction.crudConsistency`, `feedbackReproduction.multiClient`, `contractSchemas`, `governanceHashIntegrity`, `governanceHashHardening`, `importDuplicateAddVisibility`.
+- **Performance baseline** (`scripts/perf-baseline.mjs`): Rewritten to connect via `@modelcontextprotocol/sdk` instead of portable client.
+- **Guard declarations** (`scripts/guard-declarations.mjs`): Simplified allow-list to only `sdk-shim.d.ts`.
+- **Config cleanup**: Removed portable references from `.eslintignore`, `.eslintrc.json`, `tsconfig.eslint.json`, `tsconfig.eslint.vendored.json`, `vitest.config.ts`, `.secrets.baseline`.
+
+## [1.6.8] - 2026-02-16
+
+### Changed
+
+- **Schema version bumped to v4**: Instruction schema now accepts `sourceWorkspace` and `createdByAgent` as optional root-level properties. These fields are set by `promote_from_repo` to track provenance of promoted entries. Previously, entries with these fields were rejected by `additionalProperties: false` validation (caused 10 skipped entries in production catalogs).
+- **Migration v3→v4**: Automatic no-op migration — fields are optional so no data transforms needed; schemaVersion stamp is updated on load.
+
+## [1.6.7] - 2026-02-16
+
+### Added
+
+- **SpecKit bootstrap**: Full spec-driven development scaffolding for the repo.
+  - `constitution.json` — Machine-checkable quality gates (quality, security, architecture, governance articles)
+  - `.specify/` folder — `memory/constitution.md`, `templates/` (spec, plan, tasks), `config/promotion-map.json`, `commands/`
+  - `.github/copilot-instructions.md` — Canonical repo instructions with MCP integration section
+  - `.github/agents/` — 5 SpecKit agent slash commands (constitution, specify, plan, tasks, implement)
+  - `.github/prompts/` — 5 matching reusable prompt files
+  - `sync-constitution.cjs` — Generates derived constitution.md from constitution.json (supports `--check` mode)
+  - `promotion-map.json` — Maps existing docs (ARCHITECTURE, PRD, TOOLS, CONTRIBUTING, specs) for catalog promotion
+
+## [1.6.6] - 2026-02-16
+
+### Added
+
+- **`promote_from_repo` tool**: New mutation tool that scans a local Git repository and promotes its knowledge content (constitutions, docs, instructions, specs) into the instruction catalog. Supports `.specify/config/promotion-map.json` for explicit source→instruction mappings and automatic `instructions/*.json` discovery. Features SHA-256 content hash dedup, scope filtering, dry-run mode, force re-promote, and custom repoId override. Replaces per-repo promotion logic with a centralized server-side tool.
+- **15 unit tests** for `promote_from_repo` covering promotion-map, instruction file scanning, scope filtering, content hash dedup, force flag, dry-run, repoId override, error handling, and malformed file resilience.
+- **TOOLS.md** documentation for `promote_from_repo` tool.
+
+## [1.6.5] - 2026-02-13
+
+### Changed
+
+- **Tool name separator**: Renamed all 44 MCP tool names from slash (`/`) to underscore (`_`) format (e.g., `health/check` → `health_check`, `instructions/dispatch` → `index_dispatch`). Underscore naming improves compatibility across MCP clients and avoids path-separator ambiguity.
+- **Dispatch schema**: Added `listScoped` and `getEnhanced` to the `index_dispatch` action enum so these actions are no longer blocked by schema validation.
+
+### Fixed
+
+- **`feedback_get` / `feedback_update` not-found handling**: Changed from throwing MCP error -32603 to returning a graceful `{ notFound: true, id, hint }` response, consistent with `index_dispatch get` behavior.
+
+### Documentation
+
+- Updated README.md, TOOLS.md, and MIGRATION.md to reflect underscore tool naming convention.
+
+## [Unreleased]
+
+### Changed (Catalog Configuration)
+
+- **Configurable body max length**: Added `INDEX_SERVER_BODY_MAX_LENGTH` environment variable (default: 20000, range: 1000–1000000) to control the maximum body character length for instruction entries. The JSON schema ceiling is 1MB; the runtime config controls effective enforcement.
+- **Enhanced salvage for missing fields**: Missing `audience` now defaults to `all` (salvage counter: `audienceMissing`), missing `requirement` defaults to `recommended` (counter: `requirementMissing`). Previously, entries without these fields were hard-rejected.
+- **Body truncation always applies**: Removed the 24K ceiling on body truncation salvage. Bodies exceeding the configured limit are always truncated, regardless of how far over they are.
+- **Near-limit warning is relative**: The `body:near-limit` soft warning now triggers at 90% of the configured body max length instead of a hardcoded 18K threshold.
+- **Rejection logging**: Schema and classification rejections are now logged to stderr at info level (`[catalog:skip] filename: reason`) for operational visibility without requiring trace mode.
+- **Schema body maxLength bumped to 1MB**: The JSON schema `instruction.schema.json` body `maxLength` raised from 20000 to 1000000 to serve as a permissive ceiling; the runtime `INDEX_SERVER_BODY_MAX_LENGTH` config controls the effective limit.
+
+### Changed (Schema & Migration)
+
+- **contentType now required**: Added `contentType` to required properties in instruction.schema.json (Schema v3)
+  - Updated `migrateInstructionRecord()` to add `contentType='instruction'` default for backward compatibility
+  - Enhanced groom handler to apply migration logic during catalog operations
+  - Updated normalize handler to ensure contentType is added to all instructions
+  - Production migration: All 138 production instructions updated with contentType field
+  - Migration scripts: Added `scripts/add-contenttype-prod.ps1` for bulk updates
+  - Reference: Schema version 3, commit 598f90d
+
+### Fixed (MCP Protocol Compliance)
+
+- **CRITICAL:** Eliminated stdout contamination violating MCP stdio transport specification. Server was writing diagnostic messages to stdout, contaminating the JSON-RPC message stream and causing PowerShell MCP client connection failures.
+  - Changed `MetricsCollector.ts`: 4 instances of `console.log()` → `console.error()` (storage mode, clear messages)
+  - Changed `memoryMonitor.ts`: 9 instances of `console.log()` → `console.error()` (monitoring lifecycle, snapshots, utilities)
+  - Fixed `sdkServer.ts`: Corrected literal `\n` escape sequences that broke TypeScript compilation
+  - Impact: stdout now contains ONLY JSON-RPC messages (MCP spec compliant), stderr contains all diagnostic/debug logging
+  - Fixes: PowerShell MCP client timeout issue caused by non-JSON lines in stdout stream
+  - Reference: https://modelcontextprotocol.io/docs/concepts/transports
+
+### Enhanced (Handshake Diagnostics)
+
+- Added comprehensive handshake diagnostic logging when `INDEX_SERVER_LOG_DIAG=1`:
+  - Early stdin buffer: Shows captured chunk preview, Content-Length detection, hasInitialize detection
+  - Replay diagnostics: Detailed chunk replay with preview of first chunk content
+  - Transport initialization: stdin listener count tracking, readable state monitoring
+  - Enhanced visibility for debugging client connection issues
+- Improved error handling for handshake buffer replay with structured error messages
+
+### Added (Testing Infrastructure)
+
+- Created `test-stdin-race.js`: Node.js test client simulating PowerShell behavior (immediate initialize)
+- Created `test-powershell-client.ps1`: PowerShell test harness for real client connection testing
+- Created `STDOUT-CONTAMINATION-FIX.md`: Comprehensive documentation of stdout contamination issue and fix
+- Created `POWERSHELL-CLIENT-ANALYSIS.txt`: Detailed analysis of PowerShell client timeout issue (13968 lines)
+
+### Changed (Previous)
+
+- Dashboard: Added performance (CPU + Memory) card visual baseline snapshot (`performance-card-*`).
+- UI: Refactored drilldown controls into horizontal grouped layout with standardized checkbox styling.
+- Tests: Promoted performance card snapshot to mandatory Playwright baseline; removed legacy optional skips via deterministic seeding.
+- Logging: Introduced dual-format (structured JSON vs concise plain) logging for WebSocket connect/disconnect/error and memory deltas using existing `INDEX_SERVER_DEBUG` / `INDEX_SERVER_VERBOSE_LOGGING` flags (no new env vars added). Multi-line memory change logs replaced with single-line structured or concise output to eliminate downstream JSON parse warnings.
+
+## [1.6.2] - 2025-09-20
+
+### Changed (configuration & mutation gating)
+
+- Unified mutation enable flag under consolidated `INDEX_SERVER_MUTATION`; legacy `INDEX_SERVER_ENABLE_MUTATION` still accepted with one-time deprecation warning via `runtimeConfig.parseMutation()`.
+- Server transport, instruction handlers, and dashboard admin panel now all query `getRuntimeConfig().mutationEnabled` ensuring consistent behavior in tests and production.
+- Updated gating error message to reference `INDEX_SERVER_MUTATION=1` (retains legacy mention for transition).
+
+### Added (test infrastructure)
+
+- Introduced shared dashboard readiness helper `waitForDashboard.ts` eliminating ad‑hoc polling loops across graph-related tests.
+
+### Fixed (flaky tests)
+
+- Stabilized `graphFiltering.spec.ts`, `graphFilteringStyles.spec.ts`, and `graphThemeVariables.spec.ts` by awaiting deterministic dashboard startup (previous 15s timeouts reduced to reliable ~15s execution within extended 20s cap).
+
+### Internal (refactor / hygiene)
+
+- Removed direct `process.env.INDEX_SERVER_ENABLE_MUTATION` hot path checks in favor of runtime configuration accessor (dynamic reload when only legacy flag present preserves prior semantics).
+- Minor import cleanup after consolidation (removed unused `getBooleanEnv` references where replaced by runtime config).
+
+### Upgrade Guidance (1.6.2)
+
+- Prefer setting `INDEX_SERVER_MUTATION=1` going forward. Existing automation using `INDEX_SERVER_ENABLE_MUTATION=1` continues to work (deprecation window). Plan future release to drop legacy flag once downstream usage metrics indicate adoption.
+- No schema or tool contract changes; safe patch update.
+
+### Future (1.6.2 follow-up)
+
+- Schedule removal of legacy mutation flag references in help text and admin dashboard after confirming negligible usage (target ≥90% replacement) and possibly introduce `INDEX_SERVER_CONFIG_STRICT` to enforce consolidated variable set.
+
+### Configuration Consolidation (Phases 1–4)
+
+- Added unified runtime configuration loader `src/config/runtimeConfig.ts` centralizing parsing & normalization of environment variables.
+- Introduced consolidated variables: `INDEX_SERVER_TIMING_JSON`, `INDEX_SERVER_TEST_MODE`, `INDEX_SERVER_LOG_LEVEL`, `INDEX_SERVER_MUTATION`, `INDEX_SERVER_TRACE` (token set), with future placeholders (`INDEX_SERVER_BUFFER_RING`).
+- Backward compatibility: legacy flags (`FAST_COVERAGE`, `MANIFEST_TEST_WAIT_DISABLED_MS`, `MANIFEST_TEST_WAIT_REPAIR_MS`, `INDEX_SERVER_ENABLE_MUTATION`, verbose/diag log flags) auto-mapped with one-time deprecation warnings.
+- Pilot migration: `manifestEdgeCases.spec.ts` refactored to consume timing via `cfg.timing()` accessor; remaining high-churn tests scheduled for follow-up phases.
+- Documentation updates: README consolidation section, deployment matrix extended with migration notes, contributing guidelines prohibit new ad-hoc env vars, configuration guide cross-referenced.
+- Coverage gating integrated with loader (`runtimeConfig.coverage`) maintaining dual-threshold (`COVERAGE_HARD_MIN`, `COVERAGE_TARGET`).
+- Established future Phase 5 plan: optional strict mode (`INDEX_SERVER_CONFIG_STRICT=1`) to reject unmapped legacy flags once adoption threshold met (target ≥70% migrated usages).
+
+
+### Added (dispatcher capabilities & batch)
+
+### Documentation (overhaul 1.4.2)
+
+- Added `docs/MANIFEST.md` detailing catalog manifest lifecycle, invariants, drift categories, opportunistic materialization, and fastload roadmap.
+- Updated `README.md` with Manifest & Opportunistic Materialization section; added MANIFEST doc links in primary doc suite lists.
+- Updated `PROJECT_PRD.md` to version 1.4.2 including formal Manifest & Materialization requirements (MF1–MF7) and ratified schema‑aided failure contract.
+- Updated `ARCHITECTURE.md` (version banner 1.4.1 → context now aligned with opportunistic materialization & manifest helper) – cross-linked manifest semantics.
+- Updated `DOCS-INDEX.md` adding Manifest category; refreshed recent updates section for 1.4.x runtime changes.
+- Removed deprecated PRD stub files (`docs/PRD.md`, `docs/PROJECT-PRD.md`) to eliminate duplication; canonical remains `docs/PROJECT_PRD.md`.
+- Ensured CHANGELOG references preserved and future fastload placeholder documented (no runtime effect yet).
+
+### Changed (readability & consistency)
+
+- Standardized terminology: "Opportunistic Materialization" (replaces ambiguous "late materialization" phrasing) across updated docs.
+- Clarified disable flag guidance for `INDEX_SERVER_MANIFEST_WRITE=0` (diagnostic/read-only only).
+
+
+### Fixed (persistence phantom write false positive)
+
+- Reclassified `instructionsPersistenceDivergence.red.spec.ts` to GREEN (`instructionsPersistenceDivergence.spec.ts`).
+- Root cause: baseline drift (IDs under test already existed) causing stable count/hash and perceived phantom writes.
+- Added adaptive assertions: if IDs are new, count/hash must change; pure overwrite path allows stable hash but guarantees visibility.
+- Removed heavy multi-flag RED gating for this scenario (now validated by normal suite).
+
+### Governance (baseline noise suppression)
+
+- Updated `scripts/guard-baseline.mjs` allow-list (noise suppression only) to include:
+  - `httpMetrics.spec.ts` (HTTP instrumentation coverage)
+  - `instructionsPersistenceDivergence.spec.ts` (adaptive GREEN replacement test)
+  - `dashboardPhase1.spec.ts` (dashboard infra wiring)
+  - `dashboardRpmStability.spec.ts` (RPM metrics stability)
+  (No minimal invariant expansion; internal baseline policy unchanged.)
+
+  ## [1.4.0] - 2025-09-13
+
+  ### Added (manifest observability & helper)
+
+  - Centralized manifest update helper `attemptManifestUpdate()` consolidates all post‑mutation catalog manifest writes (future hook point for batching/debounce without changing call sites).
+  - Structured manifest write log lines: `[manifest] wrote catalog-manifest.json count=<entryCount> ms=<duration>` emitted only on successful writes.
+  - New counters:
+    - `manifest:write` – incremented on each successful manifest write
+    - `manifest:writeFailed` – incremented when an exception occurs during write
+    - `manifest:hookError` – incremented when update hook invocation throws
+  - Environment flag `INDEX_SERVER_MANIFEST_WRITE=0` disables manifest persistence (read-only / diagnostic mode) while allowing normal runtime behavior.
+
+  ### Fixed (visibility flake)
+
+  - Stabilized intermittent add → immediate list/get visibility timing by refining late materialization path and adding targeted retry logic in `addVisibilityInvariant.spec.ts` (single bounded retry, preserves genuine failure signal).
+
+  ### Tests (edge coverage)
+
+  - New `manifestEdgeCases.spec.ts` validating:
+    - Disabled write mode respects `INDEX_SERVER_MANIFEST_WRITE=0` (no file created/modified)
+    - Corrupted on-disk manifest auto‑repair after subsequent catalog mutation
+  - Visibility invariant test enhanced with diagnostic trace & retry instrumentation (now consistently green).
+
+  ### Documentation
+
+  - README: Added Manifest Observability section, documented new counters & `INDEX_SERVER_MANIFEST_WRITE` flag plus reserved `INDEX_SERVER_MANIFEST_FASTLOAD` (planned fast load optimization – inactive placeholder).
+  - CONFIGURATION guide: Added Manifest Configuration section & environment variable table entries.
+  - CHANGELOG: This entry formalizes helper + observability release.
+
+  ### Internal (refactor & safety)
+
+  - Removed scattered try/catch blocks around manifest writes in instruction mutation handlers; all now route through helper ensuring unified error handling & metrics.
+  - Preserved existing manifest drift detection & repair logic (no behavioral change when flag unset).
+
+  ### Compatibility (1.4.0)
+
+  - No instruction schema or tool interface changes.
+  - Purely additive logging & metrics; safe transparent upgrade for all clients.
+  - When `INDEX_SERVER_MANIFEST_WRITE=0`, runtime skips writes silently (counter increments suppressed) – intended only for diagnostics / perf profiling.
+
+  ### Upgrade Guidance (1.4.0)
+
+  - Pull & rebuild – no client changes required.
+  - To disable manifest file writes for diagnostics: set `INDEX_SERVER_MANIFEST_WRITE=0` (do not use in production if you rely on external manifest consumers).
+  - Monitoring systems may now scrape manifest counters alongside existing metrics buckets.
+
+  ### Future (not included – 1.4.0 roadmap)
+
+  - Planned `INDEX_SERVER_MANIFEST_FASTLOAD` optimization mode (hash/mtime short‑circuit) reserved; currently no effect (documented as placeholder only).
+
+## [1.4.1] - 2025-09-14
+
+### Fixed (dashboard health accuracy)
+
+- Resolved persistent false positive "Statistics unavailable" issue: local `statsAvailable` shadowed global flag so health card always injected the warning despite successful stats fetches. Now uses `window.statsAvailable` consistently.
+- Restored memory utilization health check (`mem: ok` / fail at ≥90% heap usage) alongside CPU derived check when backend omits explicit entries.
+
+### Changed (UI consistency)
+
+- Unified overview card styling with Real‑time Monitoring card via new shared `.stat-row` styles (consistent spacing, typography, separators).
+- Added stronger label/value contrast and tabular numeric alignment across System Statistics, System Health, and Performance cards.
+
+### Internal (refactor / cleanup)
+
+- Removed accidentally injected diagnostic block from `applyInstructionTemplate` (caused earlier syntax noise during patch).
+- Hardened health rendering defensive normalization & comments clarifying derived check thresholds (CPU <85% ok, Memory <90% ok).
+
+### Notes (1.4.1)
+
+- Pure UI + client-side logic update; no API or schema changes.
+- Safe patch upgrade; no restart flags required beyond standard rebuild/deploy.
+
+### Upgrade Guidance (1.4.1)
+
+- Pull, rebuild, redeploy. Dashboard automatically reflects new styling; no configuration changes.
+
+
+## [1.2.1] - 2025-09-05
+
+## [1.3.0] - 2025-09-10
+
+## [1.3.1] - 2025-09-11
+
+### Fixed (governance overwrite semantics)
+
+- Added safe metadata-only overwrite hydration: when `overwrite:true` and body omitted, handler now hydrates existing body/title before validation allowing pure governance updates (e.g., priority + version bump) without resending full content.
+- Corrected `overwritten` flag reporting for metadata-only higher version updates (previously returned `overwritten:false`).
+- Enforced strict semantic version validation on create path (previously only validated updates) returning `invalid_semver` for malformed versions.
+
+### Internal (test reliability)
+
+- Targeted governance versioning tests now all green: auto bump, non-semver rejection, body change bump requirements, metadata-only version increment.
+- Added hydration logic with type-safe mutation (no `any` casts) to satisfy linting.
+
+### Notes (1.3.1 governance follow-up)
+
+- No changes to on-disk schema; patch release focused on correctness & ergonomics.
+- Recommended for users performing frequent governance-only edits to reduce payload size and maintain accurate overwrite telemetry.
+
+### Added (schema v3 & governance)
+
+- Introduced on-disk instruction schemaVersion `3` with new `primaryCategory` field enforcing a single canonical category reference.
+- Automatic migration path (v1→v2→v3) updates existing instruction JSON files in-place; adds `primaryCategory` from first existing category and normalizes category list to include it.
+- Added governance justification file `governance/ALLOW_HASH_CHANGE` documenting approved hash shift from structural canonicalization.
+
+### Changed (migration & normalization)
+
+- `migrateInstructionRecord` now injects `primaryCategory` for v2 records and ensures `schemaVersion` bump with descriptive notes.
+- Runtime handlers enforce invariant: `primaryCategory ∈ categories[]`; fallback category `uncategorized` only when INDEX_SERVER_REQUIRE_CATEGORY unset.
+- All committed instructions canonicalized (hash drift resolved) to provide stable CI governance baseline.
+
+### Integrity & Tooling
+
+- Full test suites (fast + slow) green post-migration; quarantined flaky tests unchanged.
+- Governance hash workflow unblocked via explicit justification artifact.
+- Production deployment updated to version `1.3.0` (no behavior regressions detected).
+
+### Compatibility
+
+- Migration is additive; older clients reading instructions ignore unknown `primaryCategory`.
+- Direct downgrade not supported; rollback requires restoring pre-migration backups.
+
+### Documentation (navigation & migration)
+
+- Updated MIGRATION guidance (v2→v3 path) and added docs index + instruction usage plan for navigation.
+
+
+### Changed (test stability)
+
+- Deprecated legacy RED test `instructionsPersistenceDivergence.red.spec.ts` -> converted to inert placeholder (historical context only).
+- Added adaptive GREEN test `instructionsPersistenceDivergence.spec.ts` (creation vs overwrite aware, synthetic hash conditional logic).
+- Eliminated 60s timeout risk from mis-gated RED reproduction path.
+
+### Added (diagnostics)
+
+- New `docs/RUNTIME-DIAGNOSTICS.md` detailing runtime triage (handshake timing, persistence verification, metrics inspection).
+
+### Integrity
+
+- Suite now green without special gating; persistence divergence scenario validated deterministically (no false positives from baseline drift).
+
+### Governance
+
+- Formal change control required (see baseline plan section 14) for any test expansion.
+
+### Handshake Hardening
+
+- Implemented early stdin buffering to prevent loss of initial `initialize` frame when clients send immediately on spawn.
+- Removed temporary extended readiness polling loops from CRUD smoke & batch/parameterized tests (now redundant).
+- Added regression test `handshakeTimingRegression.spec.ts` asserting timely initialize response (<15s hard cap, soft warn >5s).
+- Locked handshake path (short-circuit mode removed, version negotiation via spec date retained).
+
+
+## [0.1.0] - 2025-08-24
+
+### Added (initial)
+
+- Initial project skeleton (models, classification, transport, instruction tools, prompt governance, documentation scaffolding).
+
+## [0.2.0] - 2025-08-25
+
+### Added (metrics & governance)
+
+- metrics, gates, usage tracking, incremental diff, integrity tools
+
+## [0.3.0] - 2025-08-25
+
+### Added (dashboard & persistence)
+
+- Add response schemas, contract tests, docs update
+
+## [0.4.0] - 2025-08-25
+
+### Added (SDK migration & enhancements)
+
+- dashboard + CLI flags; import/export/repair/reload; meta_tools; usage persistence; schema extensions
+
+## [0.5.0] - 2025-08-25
+
+### Changed (supporting artifacts)
+
+- Migrated to official @modelcontextprotocol/sdk (removed legacy custom transport)
+- Standardized initialize handshake requiring clientInfo + capabilities.tools
+- Structured JSON-RPC error codes/data (-32602 params, -32601 method, -32603 internal)
+
+### Added (tests & tooling)
+
+- server/ready notification via SDK oninitialized hook
+- initialize result now includes human-readable instructions field
+- ping request handler for lightweight health/latency
+- Enhanced unknown tool & mutation gating error data (message, method/tool)
+
+## [0.5.1] - 2025-08-25
+
+### Added (removal capability)
+
+- New mutation tool `index_remove` to delete one or more instruction entries by id (requires INDEX_SERVER_ENABLE_MUTATION=1)
+
+### Changed (registry)
+
+- Tool registry & schemas updated to expose remove capability
+
+## [0.5.2] - 2025-08-25
+
+### Added (single add capability)
+
+- New mutation tool `index_add` (single entry, lax mode default filling, optional overwrite)
+
+### Changed (result shape & docs)
+
+- Aligned result shape for skip path (always includes created/overwritten booleans)
+- Updated docs and schemas to reflect new tool
+
+## [0.5.3] - 2025-08-25
+
+### Added (catalog grooming)
+
+- New mutation tool `index_groom` for normalization, duplicate merging, hash repair, deprecated cleanup (supports dryRun mode)
+
+### Changed (registry & docs)
+
+- Added schema, registry entry, tests, and documentation for grooming
+
+## [0.6.0] - 2025-08-25
+
+### Added (structured scoping)
+
+- Introduced structured scope fields on instructions: workspaceId, userId, teamIds
+- Classification now derives these from legacy category prefixes (scope:workspace:*, scope:user:*, scope:team:*) and strips them from categories
+- New read-only tool `instructions/listScoped` selects best matching scope (user > workspace > team > all)
+- JSON Schemas, registry version, and package version bumped
+
+### Changed (groom enhancement)
+
+- Groom tool now supports `purgeLegacyScopes` mode flag removing legacy scope:* category tokens and reports `purgedScopes` metric
+
+### Notes (1.0.3)
+
+- Backward compatibility: existing category-based scope prefixes still recognized; groom tool can later remove them
+
+## [0.7.0] - 2025-08-25
+
+### Changed (Tier 1 schema simplification)
+
+- Relaxed instruction JSON schema: only authoring essentials now required (`id,title,body,priority,audience,requirement,categories`)
+- `additionalProperties` enabled to allow forward-compatible governance extensions without breaking authors
+- Loader & enrichment narrowed: removed automatic placeholder injection for most governance fields (now derived in-memory)
+
+### Added (dispatcher)
+
+- Minimal author path test (`minimalAuthor.spec.ts`) ensuring derivation of version, priorityTier, semanticSummary, review cycle
+- Multi-add persistence test clarifying intentional ignoring of user-supplied governance overrides in `index_add`
+
+### Removed / Simplified
+
+- Excess placeholder governance fields from test fixtures and baseline instruction JSON files
+- Enrichment tool now only persists missing `sourceHash`, `owner` (if auto-resolved), `priorityTier`, `semanticSummary`
+
+## [0.8.0] - 2025-08-25
+
+### Added (governance patching)
+
+- New mutation tool `index_governanceUpdate` enabling controlled patch of `owner`, `status`, review timestamps, and optional semantic version bump (`patch|minor|major`)
+- README documentation for simplified schema + governance patch workflow
+
+### Changed (schemas & docs)
+
+- Tool registry updated (schema + mutation set) and description added
+- Registry version implicitly advanced; package version bumped
+
+### Rationale (consolidation)
+
+- Decouples routine content edits from governance curation; reduces author friction while maintaining an auditable lifecycle
+
+## [0.9.0] - 2025-08-27
+
+### Breaking (dispatcher consolidation)
+
+- Removed legacy read-only instruction tools: `instructions/list`, `instructions/listScoped`, `instructions/get`, `index_search`, `instructions/diff`, `instructions/export`
+- Added unified dispatcher tool `index_dispatch` supporting actions: `list`, `listScoped`, `get`, `search`, `diff`, `export`, `query`, `categories`, `dir`, plus mutation/governance actions: `add`, `import`, `remove`, `reload`, `groom`, `repair`, `enrich`, `governanceHash`, `governanceUpdate`, `health`, `inspect`, `dir`, `capabilities`, `batch`
+- Tests and internal registry updated to only surface `index_dispatch` (reduces tool surface for clients, simplifies capability negotiation)
+
+### Added
+
+- Dispatcher batch execution (`action: "batch"`) to perform multiple sub-actions in one round trip
+- Capabilities action returning: `{ version, supportedActions, mutationEnabled }`
+- Negative schema drift test migrated to dispatcher schema
+- Regenerated `docs/TOOLS-GENERATED.md` to reflect dispatcher (single tool surface + flexible schema)
+- Added dispatcher capabilities & batch test suites (`dispatcherCapabilities.spec.ts`, `dispatcherBatch.spec.ts`)
+
+### Changed
+
+- Schemas: removed per-method instruction response schemas; introduced flexible dispatcher response schema (loose anyOf) for rapid iteration
+- Documentation (TOOLS, PRD) pending full rewrite to reflect dispatcher (will land immediately post-merge)
+
+### Migration Guide (1.0.0)
+
+| Old | New (dispatcher) |
+|-----|------------------|
+| instructions/list | index_dispatch { action:"list", ... } |
+| instructions/listScoped | index_dispatch { action:"listScoped", ... } |
+| instructions/get | index_dispatch { action:"get", id } |
+| index_search | index_dispatch { action:"search", q } |
+| instructions/diff | index_dispatch { action:"diff", clientHash?, known? } |
+| instructions/export | index_dispatch { action:"export", ids?, metaOnly? } |
+
+### Rationale (1.0.0)
+
+Unifying read-only catalog operations behind a single tool reduces handshake/tool enumeration overhead, enables richer batching, and provides a single stability / gating surface. Future specialized actions (advanced query planner) can ship without expanding the top-level tool set.
+
+## [0.9.1] - 2025-08-27
+
+### Changed (test suite & reliability)
+
+- Eliminated all skipped tests; expanded suite to 125 assertions across 69 files (dispatcher, governance hash stability, enrichment, error paths, property-based grooming, usage gating).
+- Strengthened dispatcher, transport core, governance update, and error-path coverage (malformed JSON-RPC, unknown methods) with deterministic waits & diagnostics.
+- Seeded property-based groom idempotence test for reproducibility.
+- Added explicit feature flag enable/disable coverage (usage gating & feature_status reporting).
+
+### Added (documentation)
+
+- Updated README test section (current counts, no skips) and clarified dispatcher-only surface & mutation gating.
+- Clarified architecture doc to reflect 0.9.x dispatcher consolidation (previous note referenced 0.8.x only).
+- Refreshed tools registry generated notes for stabilization pass.
+
+### Internal (1.0.0)
+
+- No API surface changes vs 0.9.0 (patch release). Dispatcher contract & tool schemas unchanged.
+- Pure documentation + test reliability improvements; safe for consumers.
+
+### Upgrade Guidance
+
+No action required for clients already on 0.9.0. Optional: pull to benefit from fuller test coverage and clarified documentation.
+
+## [1.0.0] - 2025-08-27
+
+### Breaking Changes
+
+- Removed all legacy direct JSON-RPC per-tool method handlers (e.g. calling `health_check` directly). Clients MUST use `tools/call` with `{ name:"<tool>" }`.
+- Removed underscore alias methods (e.g. `health_check`, `metrics_snapshot`, `usage_track`, etc.). Canonical slash-form tool names only.
+- Removed fallback minimal stdio transport path (SDK transport now required; process exits fast if unavailable).
+- Removed Ajv validation layer for direct handlers (tool argument validation remains schema-based internally where needed or enforced by tool logic).
+
+### Added / Changed
+
+- Simplified handshake: deterministic ordering `initialize` response -> single `server/ready` -> optional `tools/list_changed` (idempotent ready emitter with trace logging via `INDEX_SERVER_HANDSHAKE_TRACE=1`).
+
+## [1.0.3] - 2025-08-28
+
+### Fixed (handshake determinism & flake elimination)
+
+- Resolved intermittent minimal handshake test flake where `initialize` result line was occasionally not captured before `server/ready` notification. Root cause: race between stdout write callback scheduling and line buffering in tight spawn harness.
+- Emit minimal server initialize response synchronously via `fs.writeSync(1, ...)` ensuring flush ordering; schedule `server/ready` via `setImmediate` for strict sequencing.
+- Hardened `minimalHandshake.spec.ts` with diagnostic dump and stricter pattern.
+
+### Added (minimal reference server)
+
+- Introduced `src/minimal/` lightweight reference implementation exercising only `initialize`, `server/ready`, `tools/list_changed`, `ping/health` pathways for rapid protocol regression detection.
+
+### Deployment
+
+- Deployment script now succeeds with added minimal server artifacts; production bundle verified post-change. Addressed earlier invalid script key by using dash form `start-minimal` (avoid colon which is invalid in npm script names on some environments).
+
+### Notes (feedback introduction)
+
+- All core handshake, latency, governance, and dispatcher suites pass consistently post-fix (multiple consecutive full runs, zero handshake ordering failures after synchronous emission patch).
+- Added structured handshake trace events (`initialize_received`, `ready_emitted`, watchdog diagnostics) for observability.
+- Hardened tool list change ordering: prevents premature `tools/list_changed` before `server/ready`.
+- Updated tests to exclusively exercise `tools/call` path (`transport.spec.ts`, `responseEnvelope.spec.ts`, latency & coverage suites).
+
+### Migration Guide
+
+| Legacy Pattern | 1.0+ Replacement |
+|----------------|------------------|
+| `{ method:"health_check" }` | `{ method:"tools/call", params:{ name:"health_check", arguments:{} } }` |
+| `{ method:"health_check" }` | (unsupported) use canonical above |
+| `{ method:"metrics_snapshot" }` | `{ method:"tools/call", params:{ name:"metrics_snapshot" } }` |
+| Direct instruction tool names (dispatcher unaffected) | Use dispatcher or existing canonical tool via tools/call |
+
+### Rationale
+
+Removing back-compat surfaces reduces ambiguity in clients, eliminates duplicate execution pathways, and tightens protocol compliance (single ready emission, no early notifications). Observability via trace events aids debugging without impacting normal stderr noise (opt-in flag).
+
+### Upgrade Notes
+
+- Update any bespoke clients or scripts invoking legacy underscore methods to the canonical names via `tools/call`.
+- Ensure environment expects a single `server/ready` notification; multi-ready tolerant clients remain unaffected.
+- If you previously relied on the fallback transport, adopt the standard MCP SDK JSON-RPC stdio framing; no additional configuration needed for normal usage.
+
+### Internal (refinement)
+
+- Removed ~300 lines of legacy compatibility code; reduced handshake race conditions and watchdog complexity.
+- Test suite adjusted; alias test removed.
+
+### Future
+
+- Potential addition: explicit protocolVersion negotiation matrix & structured `capabilities.handshake` section once MCP spec advances.
+
+## [1.0.1] - 2025-08-27
+
+### Changed (semantic error guarantees)
+
+- Hardened JSON-RPC semantic error preservation: dispatcher validation/gating codes (-32601 / -32602) are now deterministically retained end-to-end (previous rare fallbacks to -32603 eliminated).
+- Added deep semantic recovery & diagnostic logging (`[rpc] deep_recover_semantic`) in `sdkServer` request override for visibility when nested wrappers obscure codes.
+- Tightened tests: removed transitional allowances for -32603 in dispatcher validation & mutation gating specs; assertions now require exact expected semantic codes.
+
+### Added (stress coverage)
+
+- New `dispatcherStress.spec.ts` high-churn test exercising rapid invalid + valid dispatcher calls to detect any semantic code downgrades.
+- Supplementary logging gated by `INDEX_SERVER_LOG_VERBOSE=1` to trace pass-through vs wrapped error paths.
+
+### Internal (maintenance)
+
+- Updated `.gitignore` to exclude transient fuzz/concurrency instruction artifacts, build locks, and temp minimal-author scratch directories.
+- Incremented package version to 1.0.1 (patch: reliability & test hardening only; no API changes).
+
+### Upgrade Guidance (1.0.1)
+
+No action required. Clients benefit from stricter and more predictable error codes; behavior of successful tool results unchanged.
+
+## [1.0.2] - 2025-08-27
+
+### Changed (test gating & stability)
+
+- Segregated nondeterministic / adversarial fuzz & stress specs behind `INDEX_SERVER_STRESS_DIAG=1` (handshake flake, mixed workload health starvation repro, multi‑process health stress, dispatcher stress/flake, concurrency fuzz).
+- Baseline test run (without flag) now deterministic: all core + compliance + governance suites green; stress specs appear as skipped (documented) eliminating prior intermittent CI noise.
+- Added skip pattern helper (`maybeIt`) in gated specs for clear opt‑in semantics.
+
+### Added (tooling & scripts)
+
+- New npm scripts: `test:stress` (full suite with stress enabled) and `test:stress:focus` (runs only gated stress specs) for quicker iterative diagnosis.
+- Added README section "Stress / Adversarial Test Suite" enumerating gated spec files and usage examples.
+
+### Diagnostics / Observability
+
+- Retained synthetic initialize fallback path but fully gated by `INDEX_SERVER_INIT_FALLBACK_ALLOW` (off by default) with compliance test (`healthMixedNoFallback.spec.ts`) ensuring no synthetic initialize in normal operation.
+- Expanded handshake trace logging clarifying fallback gating decisions (`init_unconditional_fallback_skip gating_off`).
+
+### CI / Reliability
+
+- Prepared nightly stress workflow (scheduled) to exercise stress suite with `INDEX_SERVER_STRESS_DIAG=1` without impacting mainline CI signal (separate job, non-blocking).
+
+### Internal (catalog & runtime)
+
+- Version bumped to `1.0.2` (patch: reliability & test ergonomics only; no API surface changes).
+
+### Upgrade Guidance (1.0.2)
+
+No client changes required. Consumers may optionally run the stress suite locally when diagnosing latency / starvation conditions:
+
+```bash
+INDEX_SERVER_STRESS_DIAG=1 npm test            # run full suite including stress
+INDEX_SERVER_STRESS_DIAG=1 npm run test:stress # equivalent convenience script
+```
+
+For routine CI or local verification omit the flag for deterministic results.
+
+## [1.0.4] - 2025-08-28
+
+### Added (feedback / emit system)
+
+- New MCP-compliant feedback tool suite:
+  - `feedback_submit`
+  - `feedback_list`
+  - `feedback_get`
+  - `feedback_update`
+  - `feedback_stats`
+  - `feedback_health`
+- Persistent JSON storage (`feedback/feedback-entries.json`) with max entry cap (`INDEX_SERVER_FEEDBACK_MAX_ENTRIES`, default 1000) and trimming.
+- Structured feedback model (type, severity, status workflow, tags, metadata, context) with audit logging.
+- Security & critical feedback entries mirrored to stderr for immediate visibility.
+- Health endpoint reporting storage accessibility, writability, configured directory.
+- Statistics endpoint aggregating totals by type/severity/status plus recent activity windows (24h/7d/30d).
+- Environment configurables: `INDEX_SERVER_FEEDBACK_DIR`, `INDEX_SERVER_FEEDBACK_MAX_ENTRIES`.
+- Documentation: README & TOOLS.md sections describing usage, schemas, and examples.
+
+### Changed (infrastructure)
+
+- `.gitignore` updated to exclude persisted feedback storage artifacts.
+- Tool registry extended with feedback tools (stable read-only vs mutation semantics maintained where applicable).
+
+### Notes (cleanup hygiene)
+
+- Feature addition only; no breaking changes to existing instruction dispatcher or governance tools.
+- Version bump to 1.0.4 reflects new externally visible tool surface.
+
+## [1.0.5] - 2025-08-28
+
+### Changed (test stability & isolation)
+
+- Refactored feedback test suite:
+  - Introduced `feedbackCore.spec.ts` (comprehensive) & `feedbackSimple.spec.ts` (smoke) with per‑test isolated `INDEX_SERVER_FEEDBACK_DIR` directories.
+  - Converted brittle absolute "empty list" assertions to delta-based assertions; legacy expectations gated with `it.skip(... // SKIP_OK)` for documentation without flakiness.
+  - Added deterministic persistence wait loop for filesystem write visibility.
+  - Replaced dynamic requires with explicit static imports (avoids MODULE_NOT_FOUND under variant names).
+  - Added legacy placeholder `feedback.spec.ts` (kept minimal) to preserve historical references.
+
+### Fixed (rate limiting correctness)
+
+- Reordered rate limiting logic in catalog usage tracking so entry creation/load occurs before limit evaluation preventing cross-id phantom rate limits.
+- Added invariants ensuring usageCount reflected accurately in rate-limited responses.
+
+### Added (governance & content guidance)
+
+- New `CONTENT-GUIDANCE.md` clarifying instruction classification, promotion workflow, and MCP protocol separation of concerns.
+- Explicit MCP compliance guidance: do NOT embed tool catalogs/schemas inside instruction content (dynamic discovery via protocol only).
+
+### Documentation (1.1.1)
+
+- Expanded TOOLS.md & README with Feedback System Features section.
+- Clarified short-circuit / minimal handshake modes and environment flags (previous sections consolidated).
+
+### Internal / Quality
+
+- Guarded optional `since` parameter access in feedback list & stats handlers (eliminates TS18048 risk under strict mode).
+- Added commit helper tasks for structured documentation and feature commits.
+- All core + contract tests passing (168 passed / 14 skipped – skips limited to explicitly gated stress & legacy expectations).
+
+### Notes (stabilization)
+
+- Patch release (1.0.5) focuses on stabilization & correctness refinements immediately following new feedback feature introduction.
+- No further tool surface changes beyond feedback system introduced in 1.0.4.
+
+### Upgrade Guidance (1.0.5)
+
+- Consumers upgrading from 1.0.4 gain improved determinism in feedback operations & safer usage rate limiting without client changes.
+
+## [1.2.0] - 2025-09-05
+
+### Added (observability & admin UX)
+
+- Unified runtime diagnostics guard (`[diag] [ISO] [category]`) capturing uncaught exceptions, unhandled rejections, process warnings, and termination signals with optional exit delay (`INDEX_SERVER_FATAL_EXIT_DELAY_MS`).
+- Real backup system with millisecond precision IDs (`backup_YYYYMMDDTHHMMSS_mmm`), manifest generation (instructionCount, schemaVersion) and safety pre-restore snapshot.
+- Admin dashboard backup listing & one‑click restore UI (auto refresh + schemaVersion display).
+- WebSocket enhancements: client UUID assignment, connect/disconnect broadcast events, immediate metrics snapshot push, active connection metrics integration.
+- Live synthetic activity per-call trace streaming over WebSocket (`synthetic_trace` messages) with runId, sequence, duration, error, and skipped markers.
+- Synthetic harness expansion to exercise instruction dispatcher CRUD pathways (`add/get/list/query/update/remove`) plus usage tracking; active in‑flight request counter + status endpoint.
+- Instruction editor enrichment: diff view, formatting button, diagnostics panel (validity, size, hash, missing fields), template injection, change detection.
+- HTTP metrics instrumentation aggregating all REST requests into pseudo tool bucket `http/request` (opt-out with `INDEX_SERVER_HTTP_METRICS=0`).
+- Performance detailed endpoint `/api/performance/detailed` (requestThroughput, avg, p95 approximation, errorRate, concurrentConnections, activeSyntheticRequests).
+
+### Changed (tests & reliability)
+
+- Added `httpMetrics.spec.ts` validating HTTP aggregation bucket increments.
+- Hardened PowerShell isolation handshake test with BOM stripping, retry initialize, soft-pass degraded mode and extended deadlines to eliminate flakes.
+- Adaptive sampling + concurrency & duration guard in multi-client feedback reproduction test (dynamic ~0.8% sample, clamped 5–8, 7s hard wallclock) reducing runtime while preserving coverage rotation.
+- Fast test script (`scripts/test-fast.mjs`) leak guard ensuring slow specs never bleed into fast subset.
+- Pre-push hook (`scripts/pre-push.ps1`) running slow test suite gating pushes.
+
+### Internal
+
+- Catalog stats now cache aggregated schemaVersion (scans bounded sample) for dashboard display & backup manifest inclusion.
+- Synthetic run summary & active request counter cached for UI polling; safety resets protect against leaked counters on errors.
+- Added cache-control headers to `/api/status` to prevent stale build/version metadata.
+
+### Notes (release rationale)
+
+- Minor version bump due to additive public capabilities (diagnostics semantics, backup/restore endpoints/UI, streaming synthetic traces, HTTP metrics exposure, instruction editor UX). No breaking tool schema changes.
+- Future roadmap items (not yet implemented): diagnostics metrics counters, JSONL sink with rotation, dashboard diagnostics endpoint, health degradation heuristics.
+
+### Upgrade Guidance (1.2.0)
+
+- No client changes required; new diagnostics lines appear only on stderr.
+- To enable HTTP metrics aggregation ensure dashboard mode is active (set `INDEX_SERVER_DASHBOARD=1`).
+- For live synthetic traces pass `?trace=1&stream=1` when invoking synthetic activity via dashboard UI (already wired in client script).
+
+## [1.0.6] - 2025-08-28
+
+### Changed (cleanup)
+
+- Removed obsolete legacy feedback test variant files (`feedback.spec.ts.new/.minimal/.disabled/.clean`) to avoid accidental resurrection and duplicate coverage.
+- Consolidated around `feedbackCore.spec.ts` (comprehensive), `feedbackSimple.spec.ts` (smoke), and minimal legacy placeholder `feedback.spec.ts` file.
+- Version bump reflects repository hygiene update post-stabilization (no functional surface changes).
+
+### Notes
+
+- Patch solely for test/developer experience cleanliness; no runtime code modifications.
+
+## [1.1.0] - 2025-08-30
+
+### Added (documented add response contract)
+
+- Finalized and documented enriched `index_add` response fields (`verified`, `feedbackHint`, `reproEntry`) in README.
+- Treats previously experimental creation verification semantics as stable API (minor bump per VERSIONING policy: additive response fields after 1.0).
+- No schema version change (response shape additive only; instruction JSON schema unchanged at `schemaVersion: 2`).
+
+### Upgrade Guidance (1.1.0)
+
+- No client changes required if ignoring unknown fields; clients wanting richer UX can surface `feedbackHint` and attach `reproEntry` when auto-filing feedback.
+- Optional: update any strict type definitions to include the new optional keys.
+
+## [1.1.1] - 2025-08-31
+
+### Changed (handshake & test harness reliability)
+
+- Removed legacy short-circuit handshake mode (`INDEX_SERVER_SHORTCIRCUIT`); only canonical SDK-driven initialize path is supported.
+- Added shared handshake helper (`src/tests/util/handshakeHelper.ts`) consolidating spawn + sentinel wait + initialize send + one-time resend fallback (idempotent initialize id=1).
+- Added timing regression guard (`handshakeTimingRegression.spec.ts`) enforcing initialize response under 15s hard cap (warn >5s) post early stdin buffering.
+- Standardized resend logic (single resend after 4s inactivity) eliminating ad-hoc polling loops that caused sporadic timeouts under suite contention.
+- Clarified diagnostic flag usage: production must keep `INDEX_SERVER_INIT_FALLBACK_ALLOW`, `INDEX_SERVER_DISABLE_INIT_SNIFF`, `INDEX_SERVER_HANDSHAKE_TRACE` unset unless actively debugging.
+
+### Fixed (intermittent test timeouts)
+
+- Resolved sporadic initialize wait timeouts in `createReadSmoke` & portable CRUD specs when run amidst heavy reproduction suites; root cause was duplicated bespoke timing logic racing process startup.
+- Direct protocol compliance test (`handshakeDirect.spec.ts`) remained stable confirming server-side sequencing correctness.
+
+### Documentation (migration & governance)
+
+- Changelog now records deprecation & removal of short-circuit path; README environment flag table implicitly authoritative (no short-circuit flag documented).
+- Next minor (1.2.0) PRD addendum will ratify handshake helper as mandatory pattern for new spawn-based specs.
+
+### Internal (1.1.1)
+
+- Patch bump only; no schema or tool surface modifications.
+
+### Upgrade Guidance (1.1.1)
+
+No action required. Remove any legacy use of `INDEX_SERVER_SHORTCIRCUIT`; standard initialize sequence already compatible.
+
+## [1.1.2] - 2025-08-31
+
+### Changed (catalog performance & visibility race elimination)
+
+- Implemented late materialization on add/get paths eliminating rare duplicate add -> immediate get notFound race under high concurrency.
+- Added per-file lifecycle tracing (`begin`, `progress`, `end`) at normal trace level for catalog loads.
+- Introduced memoized catalog caching (mtime/size heuristic + optional SHA-256 hash path) gated by `INDEX_SERVER_MEMOIZE` / `INDEX_SERVER_MEMOIZE_HASH` while preserving `INDEX_SERVER_ALWAYS_RELOAD` semantics.
+- Emitted cache summary trace (`catalog:cache-summary`) for observability (hit/miss, strategy, counts).
+
+### Fixed (multi-client visibility anomalies)
+
+- Resolved cross-client immediate visibility lag after duplicate add with overwrite=false by deferring reconstruction until atomic write + canonical readback complete.
+- Eliminated list/get sampling phantom mismatches (analyzer now reports 0 anomalies across large trace corpus).
+
+### Added (tracing & analysis tooling)
+
+- Standardized trace persistence format to bracketed label + JSON for analyzer compatibility.
+- Added trace analysis scripts (`scripts/analyze-traces.*`) and reproduction harness (`scripts/run-feedback-repro-with-trace.ps1`).
+- Minimal instruction assembly script (`scripts/prepare-minimal-instructions.mjs`) for performance-focused runs without altering tests.
+
+### Notes (release scope)
+
+- Patch release (1.1.2) is internal reliability + performance; no external tool / schema surface change.
+- All previously RED reproduction tests now GREEN; two legacy RED specs still intentionally failing due to unsupported bulk import pathway (guarded by test expectations).
+
+### Upgrade Guidance (1.1.2)
+
+No client changes required. Enable `INDEX_SERVER_MEMOIZE=1` (and optionally `INDEX_SERVER_MEMOIZE_HASH=1`) to reduce reload overhead in high-churn scenarios without sacrificing correctness.
+
+## [1.0.7] - 2025-08-30
+
+### Added (creation verification & failure contract)
+
+- Hardened `index_add` success semantics: `created:true` now only emitted after atomic write, catalog visibility, and final readability (title/body non-empty) verification; response includes `verified:true` when these checks pass.
+- Unified failure response contract via internal `fail()` helper returning `{ created:false, error, feedbackHint, reproEntry }` across all add failure paths (missing entry/id/required fields, governance violations, write errors, atomic readback failure, invalid shape).
+- Added enriched guidance encouraging clients to submit structured feedback with embedded `reproEntry` for rapid defect triage.
+- New tests: `instructionsAddCreatedFlag.spec.ts` verifying created/verified gating and feedback guidance on failure conditions (governance + required field omissions).
+- Portable client CRUD harness stabilized (dynamic ESM import shim) with deterministic atomic visibility assertions.
+
+### Documentation (lifecycle)
+
+- Added `FEEDBACK-DEFECT-LIFECYCLE.md` formalizing feedback → red test → fix → coverage workflow.
+- Pending README & TOOLS doc updates for enriched add response (will be completed in 1.1.0 minor bump).
+
+### Internal (stability)
+
+- Introduced ambient module declaration for portable client to resolve TS7016 without expanding `tsconfig` include surface.
+- Eliminated intermittent “No test suite found” flake in portable CRUD atomic spec via stabilization of file export timing.
+
+### Versioning Notes (next minor)
+
+- Patch release retained (1.0.7) while evaluating whether enriched add response should be treated as a documented stable contract.
+- Next release should bump MINOR to 1.1.0 once documentation references are finalized (optional field additions per policy).
+
+
+## [1.5.0] - 2025-09-14
+
+### Added (bootstrap gating & safety)
+
+- Bootstrap confirmation gating flow (`requestBootstrapToken` → `finalizeBootstrapToken`) requiring explicit human confirmation artifact before enabling broad mutation operations.
+- Minimal allow‑listed seed instruction IDs (000 / 001) excluded from recursion and leakage risk metrics to guarantee a safe tool discovery baseline.
+- Human confirmation persistence (`bootstrap.confirmed.json`) with token TTL enforcement and rejection reasons (`mutation_blocked`, `token_invalid`, `token_expired`).
+
+### Added (governance & risk instrumentation)
+
+- Recursion/leakage risk metrics capturing self‑referential or cyclic instruction body/category link detection; aggregated risk summary surfaced via governance hash pathways.
+- Performance baseline tooling (`perf-baseline.mjs`, compare, trend, summary scripts) now integrated with release workflow enabling drift detection on CPU time & RSS.
+- Baseline auto-confirm test helper (`forceBootstrapConfirmForTests`) gated by `INDEX_SERVER_BOOTSTRAP_AUTOCONFIRM` for legacy suite compatibility without weakening production gating semantics.
+
+### Changed (test infrastructure)
+
+- Global test setup (`setupDistReady.ts`) defaults `INDEX_SERVER_BOOTSTRAP_AUTOCONFIRM=1` unless explicitly disabled, restoring green for historical mutation suites while preserving a dedicated authentic gating spec.
+- `bootstrapGating.spec.ts` isolated via per‑test temporary `INDEX_SERVER_DIR` ensuring real token lifecycle coverage (block → issue token → finalize → unblocked).
+- Dispatcher P1 unit test adapted to force confirmation post dynamic import keeping focus on catalog ordering semantics.
+
+### Governance (baseline change control)
+
+- Added §14.5 BASELINE-CR (noise‑suppression allow‑list) to `INTERNAL-BASELINE.md` covering bootstrap gating, manifest lifecycle & schema validation, governance recursion guard, search/versioning, graph export enriched/mermaid variants, onboarding helper, and visibility invariant spec (early warning only).
+- Updated baseline sentinel and guard allow-list (noise suppression only; minimal invariant suite unchanged per §6 baseline plan).
+
+### Notes (1.5.0)
+
+- Minor release justified by additive safety gating mechanism and new performance & risk instrumentation surfaces; no breaking tool schema changes.
+- Production deployments must perform a one‑time bootstrap confirmation; tests emulate confirmation automatically unless deliberately disabled.
+- Future hardening roadmap: elevate selected noise‑suppression specs (manifest fastload, recursion guard) to minimal invariant status via separate BASELINE-CR once semantics fully stabilized.
+
+### Upgrade Guidance (1.5.0)
+
+1. Pull & rebuild (`npm ci && npm run build`).
+2. Start server; obtain bootstrap token via governance tool / log prompt; finalize to enable general mutation.
+3. For CI deterministic runs ensure `INDEX_SERVER_BOOTSTRAP_AUTOCONFIRM=1` (unless explicitly validating gating flow) and keep `BASELINE_ENFORCE=1` for guard execution.
+4. Monitor performance baseline summaries for drift (`npm run perf:drift`).
+
+## [1.13.0] - 2026-03-27
+
+## [1.15.0] - 2026-03-31
+
+### Added
+
+- Rename catalog_* MCP tools to index_*, add dashboard panel help docs, fix restore script zip support
+
+## [1.16.2] - 2026-04-02