yvgude--lean-ctx/docs/IMPLEMENTATION_PROTOCOL.md

# Implementation Protocol — SocratiCode Case-Killer (v3.4.7)

Living document tracking all implementation work for the "SocratiCode Case-Killer" roadmap.

**Goal**: lean-ctx becomes the **local-first Context Runtime Layer** for AI Coding Agents — not just compression, but **Discovery + Impact + Artifacts + Governance**. Developers/teams don't need a separate Codebase-Index-SaaS because lean-ctx delivers the same core capabilities locally + self-hosted.

---

## Reality check (verified entrypoints)

This doc is only useful if it matches what users can actually invoke.

- **GitLab source of truth**: Primary repo is `root/lean-ctx` on `gitlab.pounce.ch`.  
  **Context‑OS Backlog** wurde (für diese Workspace‑Automation) in `pounce/pounce` (Project ID **1**) angelegt; siehe `server.md` (Token‑Scope).
- **MCP tool `ctx_pack` is real and dispatched**: `LeanCtxServer::dispatch_utility_tools` has a `\"ctx_pack\"` arm calling `crate::tools::ctx_pack::handle(...)`.
- **CLI `lean-ctx pack` and `lean-ctx index` were NOT wired previously** (so `lean-ctx pack --pr` / `lean-ctx index status` would just print global help).
  - They are now wired in code via `rust/src/cli/dispatch.rs` and implemented in `rust/src/cli/pack_cmd.rs` + `rust/src/cli/index_cmd.rs`.
  - Both were smoke-tested locally:
    - `lean-ctx pack --pr --json --depth 2 --base HEAD~1`
    - `lean-ctx index status`

**Important**: In the released `v3.4.7` binary, some entrypoints were missing (CLI wiring + tool manifest entries). The implementation is present in code, but discovery/wiring required follow-up work.

---

## Context OS — Phase 1 (Hardening + Positioning) — Execution Log

### 2026-05-02 — Kickoff: SSOT/Drift Gates + Website Nav Hardening

**Ziel**: Tool-/Docs‑Drift eliminieren und die Website‑IA in Richtung „Context OS (5 Pillars)“ umbauen.

- **SSOT Manifest Gate**:
  - `cargo run --example gen_mcp_manifest --features dev-tools` regeneriert `website/generated/mcp-tools.json`
  - `rust/tests/mcp_manifest_up_to_date.rs` failt jetzt hart, wenn `website/` existiert aber `mcp-tools.json` fehlt (kein stilles Skip mehr)
- **Docs Claim Drift Gate v1**:
  - Neues CI‑Gate `rust/tests/docs_tool_counts_up_to_date.rs` (Tool‑Count Claims ↔ Runtime SSOT)
- **Docs/Template Harmonisierung**:
  - Zentrale Docs/Templates/Skills/Readmes auf den aktuellen SSOT‑Tool‑Count gebracht
- **Website (deploy worktree)**:
  - Hardcoded Tool‑Count `(46)` entfernt (Header + Docs Sidebar + Docs Changelog Sidebar)
  - Count wird aus `website/generated/mcp-tools.json` gelesen
  - IA v2 umgesetzt: `contextOsIa.ts`, Header+DocsSidebar auf 5 Pillars, neue Landings (`/docs/context-os` + `/docs/context-*`) inkl. Locale‑Routen
  - Redirect‑Stubs (301) für `/docs/pillars/*` in `website/nginx.conf`
  - SSOT Tools synced: Deploy‑Manifest auf **53 Tools** aktualisiert (inkl. `ctx_call`, `ctx_pack`, `ctx_index`, `ctx_artifacts`), Tool‑Enrichments erweitert, Tool‑Pages neu generiert; `validate-manifest` prüft zusätzlich Sync `public/generated/mcp-tools.json` ↔ `generated/mcp-tools.json`; `/docs/tools` rendert Kategorien/Tools dynamisch aus SSOT.

**Evidence**:
- `cd rust && cargo test --all-features`
- `cd rust && cargo test --test mcp_manifest_up_to_date`
- `cd rust && cargo test --test docs_tool_counts_up_to_date`
- `cd website && npm run validate:manifest` (deploy worktree)

**GitLab Tickets (Context‑OS)**:
- `0.1` Pillar Navigation + Redirect Plan → closed
- `0.2` Docs SSOT Pipeline → closed
- `4.6` Docs Claim Drift Gate v1 → closed

### 2026-05-02 — Context I/O Contracts v1 (EPIC 1: Reads/Shell/Search/Edit)

**Ziel**: Deterministische, reproduzierbare I/O Outputs (gleiches Input, gleicher State, gleiche Limits) und Premium UX ohne verwirrende Stubs.

- **1.1 ctx_read Cache Correctness v1** (`#2303`):
  - mtime validation in Cache-Entries, stale detection, premium handling fuer prompt-stale Situationen
  - Relevant: `rust/src/core/cache.rs`, `rust/src/tools/ctx_read.rs`, `rust/src/server/dispatch/read_tools.rs`
- **1.2 ctx_shell Contract v1** (`#2304`):
  - `raw` und `bypass` Flags als explicit args, klare precedence gegen Env (`LEAN_CTX_RAW`, `LEAN_CTX_DISABLED`)
  - Output-Modifikatoren (savings_note, mismatch hints) werden in raw/bypass unterdrueckt, damit Output unveraendert bleibt
  - Relevant: `rust/src/server/dispatch/shell_tools.rs`, `rust/src/tool_defs/granular.rs`
- **1.3 Search I/O Determinism v1** (`#2305`):
  - `ctx_search`: deterministische File-Traversal Reihenfolge (Paths gesammelt und lexikographisch sortiert), damit `max_results` Truncation reproduzierbar ist
  - `ctx_semantic_search`: deterministische Tie-Breaks bei gleichen RRF Scores via sekundäre Keys (file_path, symbol_name, start_line, end_line)
  - BM25 Index Search: deterministische Sortierung auch bei Score-Ties (verhindert HashMap-Iteration-Order Leaks)
  - Schema: `ctx_search ignore_gitignore` Flag (default respektiert `.gitignore`)
  - Relevant: `rust/src/tools/ctx_search.rs`, `rust/src/tools/ctx_semantic_search.rs`, `rust/src/core/vector_index.rs`, `rust/src/server/dispatch/shell_tools.rs`, `rust/src/tool_defs/granular.rs`
- **1.4 ctx_edit Contract v1** (`#2306`):
  - Preimage Guards: expected_md5, expected_size, expected_mtime_ms optional; mismatch failt ohne Write
  - TOCTOU Guard: Preimage wird vor Commit erneut gelesen; bei Abweichung Abbruch (kein partial write)
  - Atomic Write: tmp file + rename; Permissions werden soweit moeglich beibehalten
  - Optional Backup + bounded redacted diff evidence (diff_max_lines, evidence Toggle)
  - Binary Safety: invalid UTF-8 wird standardmaessig abgelehnt; allow_lossy_utf8 ist explizites Opt-in
  - Relevant: `rust/src/tools/ctx_edit.rs`, `rust/src/server/dispatch/read_tools.rs`, `rust/src/tool_defs/granular.rs`
- **1.5 I/O Boundary Contract v1** (`#2307`):
  - Zentraler Boundary Helper (`rust/src/core/io_boundary.rs`) + Role IO Policy (warn|enforce, allow_secret_paths, allow_ignore_gitignore)
  - `resolve_path` routed ueber boundary + PolicyViolation Events bei Denials/Warnungen
  - `ctx_search`: secret-like files werden standardmaessig geskippt; `ignore_gitignore` nur mit expliziter Policy (admin)
  - `linkedProjects` und `artifacts` Resolution nutzt Boundary; secret-like artifacts werden fuer non-allowed roles verworfen
  - Symlink escape test in PathJail
  - Relevant: `rust/src/core/io_boundary.rs`, `rust/src/core/roles.rs`, `rust/src/tools/mod.rs`, `rust/src/tools/ctx_search.rs`, `rust/src/server/dispatch/shell_tools.rs`, `rust/src/core/pathjail.rs`

**Evidence (lokal, minimal)**:
- `cd rust && cargo test -q --test mcp_manifest_up_to_date`
- `cd rust && cargo test -q bm25_search_sorts_ties_deterministically`
- `cd rust && cargo test -q rrf_merge_hybrid_is_deterministic_on_ties`
- `cd rust && cargo test -q search_results_are_deterministically_ordered_by_path`
- `cd rust && cargo test -q ctx_edit`
- `cd worktrees/deploy-ctxos/website && npm run -s validate:manifest`
- `cd rust && cargo test -q io_boundary`
- `cd rust && cargo test -q pathjail`
- `cd rust && cargo test -q ctx_search`

**GitLab Tickets (Context‑OS)**:
- `#2303` ctx_read Cache Correctness v1 → closed
- `#2304` Shell I/O Contract v1 → closed
- `#2305` Search I/O Determinism v1 → closed
- `#2306` ctx_edit Contract v1 → closed
- `#2307` I/O Boundary Contract v1 → closed

### 2026-05-02 — Redaction + Secret Safety v1 (EPIC 4: Verification)

- **4.4 Redaction + Secret Safety v1** (`#2327`):
  - Zentral: `rust/src/core/redaction.rs` (deterministische Pattern-Redaction)
  - Policy: non-admin roles → redaction immer aktiv; admin kann via `io.redact_outputs=false` deaktivieren
  - Wiring: `ctx_read`/`ctx_search`/`ctx_shell` Outputs redacted; persisted archives werden vor Write redacted
  - CI Gate: `rust/tests/secret_scan_artifacts.rs` (scan committed generated artifacts + docs)
  - Docs: `SECURITY.md` Threat Model (v1)
  - Relevant: `rust/src/core/redaction.rs`, `rust/src/tools/ctx_read.rs`, `rust/src/tools/ctx_search.rs`, `rust/src/server/dispatch/shell_tools.rs`, `rust/src/server/mod.rs`, `rust/tests/secret_scan_artifacts.rs`, `SECURITY.md`

**Evidence (lokal, minimal)**:
- `cd rust && cargo test -q redaction`
- `cd rust && cargo test -q --test secret_scan_artifacts`
- `cd rust && cargo run -q --example gen_mcp_manifest --features dev-tools`
- `cd worktrees/deploy-ctxos/website && npm run -s validate:manifest`

**GitLab Tickets (Context‑OS)**:
- `#2327` Redaction + Secret Safety v1 → closed

### 2026-05-02 — Output Verification Contract v1 (EPIC 4: Verification)

- **4.1 Output Verification Contract v1** (`#2324`):
  - Config surface: `VerificationConfig.mode` (off|warn|fail) als expliziter Modus (strict_mode bleibt als Legacy-Alias kompatibel)
  - WARN/FAIL Semantik: `format_compact()` ist deterministisch (sorted keys via BTreeMap) und stabil parsebar
  - Strict mode Tests: Medium+High → FAIL; non-strict: nur High → FAIL
  - Relevant: `rust/src/core/output_verification.rs`, `rust/src/core/profiles.rs`, `rust/src/server/mod.rs`

**Evidence (lokal, minimal)**:
- `cd rust && cargo test -q output_verification`

**GitLab Tickets (Context‑OS)**:
- `#2324` Output Verification Contract v1 → closed

### 2026-05-02 — Proof Artifact Format v1 + Export Tool (EPIC 4: Verification)

- **4.2 Proof Artifact Format v1** (`#2325`):
  - JSON Schema: `ContextProofV1` (`rust/src/core/context_proof.rs`) — verifier snapshot + SLO snapshot + pipeline stats + context ledger summary + bounded tool receipts
  - Export tool:
    - **MCP**: `ctx_proof action=export ...` (dispatch via `rust/src/server/dispatch/utility_tools.rs`)
    - **CLI**: `lean-ctx proof ...` (`rust/src/cli/proof_cmd.rs`)
  - Writes: `.lean-ctx/proofs/context-proof-v1_*.json` (atomic write; proof output is always redacted)
  - Website (deploy): tool pages + enrichments + manifest validation updated (56+ tools)
  - Relevant: `rust/src/core/context_proof.rs`, `rust/src/tools/ctx_proof.rs`, `rust/src/server/dispatch/utility_tools.rs`, `rust/src/tool_defs/granular.rs`, `rust/src/cli/proof_cmd.rs`, `worktrees/deploy-ctxos/website/generated/tool-enrichments.json`

**Evidence (lokal, minimal)**:
- `cd rust && cargo test -q context_proof`
- `cd rust && cargo run -q --bin lean-ctx -- proof --summary --no-write`
- `cd rust && cargo run -q --example gen_mcp_manifest --features dev-tools && cargo test -q --test mcp_manifest_up_to_date`
- `cd worktrees/deploy-ctxos/website && npm run -s generate:tools && npm run -s validate:manifest`

**GitLab Tickets (Context‑OS)**:
- `#2325` Proof Artifact Format v1 → closed

### 2026-05-02 — Replayability Contract v1 + CI Gates (EPIC 4: Verification)

- **4.3 Replayability Contract v1 + CI Gates** (`#2326`):
  - CI gates: `cargo fmt --check`, `cargo clippy -D warnings`, manifest drift gate (`gen_mcp_manifest` + `git diff` + `mcp_manifest_up_to_date`), verification gates (`output_verification`, `context_proof`, `secret_scan_artifacts`)
  - Bench regression subset: `rust/tests/savings_verification.rs` als lightweight threshold gate (allow-failure auf non-default branches; hard-fail auf default/tags)
  - Docs (deploy website): Replayability page dokumentiert jetzt die konkreten Gates + proof export
  - Relevant: `ci/gitlab-ci.yml`, `rust/tests/savings_verification.rs`, `worktrees/deploy-ctxos/website/src/page-templates/DocsReplayabilityPage.astro`

**Evidence (lokal, minimal)**:
- `cd rust && cargo fmt`
- `cd rust && cargo clippy --all-features -- -D warnings`
- `cd rust && cargo run -q --example gen_mcp_manifest --features dev-tools && cargo test -q --test mcp_manifest_up_to_date`
- `cd rust && cargo test -q output_verification && cargo test -q context_proof`
- `cd rust && cargo test -q --test secret_scan_artifacts`
- `cd rust && cargo test -q --test savings_verification`
- `cd worktrees/deploy-ctxos/website && npm run -s validate:doc-claims`

**GitLab Tickets (Context‑OS)**:
- `#2326` Replayability Contract v1 + CI Gates → closed

### 2026-05-02 — Verification Observability v1 (EPIC 4: Verification)

- **4.5 Verification Observability v1** (`#2328`):
  - Tool: `ctx_verify action=stats format=summary|json|both` (versionierter Snapshot; no raw content)
  - CLI: `lean-ctx verify --json`
  - Schema: `VerificationObservabilityV1` (`schema_version=1`) → verifier snapshot + SLO snapshot + budgets + proof counters + pipeline stats
  - Proof counters: `context_proof` tracked collected/written + last_written timestamp (count-only)
  - Deploy website: tool pages + enrichments + docs updated (56+ tools)
  - Relevant: `rust/src/core/verification_observability.rs`, `rust/src/tools/ctx_verify.rs`, `rust/src/server/dispatch/utility_tools.rs`, `rust/src/tool_defs/granular.rs`, `rust/src/cli/verify_cmd.rs`

**Evidence (lokal, minimal)**:
- `cd rust && cargo test -q verification_observability`
- `cd rust && cargo run -q --bin lean-ctx -- verify --json`
- `cd rust && cargo run -q --example gen_mcp_manifest --features dev-tools && cargo test -q --test mcp_manifest_up_to_date`
- `cd worktrees/deploy-ctxos/website && npm run -s generate:tools && npm run -s validate:manifest && npm run -s validate:doc-claims`

**GitLab Tickets (Context‑OS)**:
- `#2328` Verification Observability v1 → closed

### 2026-05-02 — Website Deploy Hardening (EPIC 0: Docs/Website)

- **0.3 Website Deploy Hardening** (`#2299`):
  - Deploy build ist jetzt **reproducible**: `website/Dockerfile` ist multi-stage (Node builder → Nginx runtime), kein pre-built dist mehr.
  - Repo hygiene: tracked `website/dist` + tracked `website/node_modules` entfernt; `.gitignore` updated (no un-ignore).
  - CI: `website_build` job nutzt `node:22.12.0`; deploy job asserted `git ls-files website/{dist,node_modules}` == 0.
  - Relevant: `worktrees/deploy-ctxos/.gitlab-ci.yml`, `worktrees/deploy-ctxos/website/Dockerfile`, `worktrees/deploy-ctxos/website/.dockerignore`, `worktrees/deploy-ctxos/.gitignore`

**Evidence (lokal, minimal)**:
- `cd worktrees/deploy-ctxos && git ls-files website/dist | wc -l` → `0`
- `cd worktrees/deploy-ctxos && git ls-files website/node_modules | wc -l` → `0`

**GitLab Tickets (Context‑OS)**:
- `#2299` Website Deploy Hardening → closed

### 2026-05-02 — Proof-first Docs Cross-Linking (EPIC 0: Docs/Website)

- **0.4 Proof-first Docs** (`#2300`):
  - Pillar-Landing-Template verlinkt jetzt Proof pages (mind. Verification + Replayability; Delivery zusätzlich Cookbook) und bleibt locale-aware.
  - Verification docs cross-linken jetzt explizit zu Trust + Replayability + Cookbook (Sidebar) → durchgängige Story ohne dead links.
  - Relevant: `worktrees/deploy-ctxos/website/src/page-templates/DocsContextOsPillarPage.astro`, `worktrees/deploy-ctxos/website/src/page-templates/DocsVerificationPage.astro`

**Evidence (lokal, minimal)**:
- `cd worktrees/deploy-ctxos/website && npm run -s validate:doc-claims`
- `cd worktrees/deploy-ctxos/website && npm run -s validate:tools`

**GitLab Tickets (Context‑OS)**:
- `#2300` Proof-first Docs → closed

### 2026-05-02 — Tools Reference IA v2 (EPIC 0: Docs/Website)

- **0.5 Tools Reference IA v2** (`#2301`) — **closed**:
  - Tools-Reference ist zusätzlich **nach Context‑OS Pillars** navigierbar:
    - `/docs/tools/context-io`
    - `/docs/tools/context-orchestration`
    - `/docs/tools/context-memory`
    - `/docs/tools/context-verification`
    - `/docs/tools/context-delivery`
  - `/docs/tools` zeigt SSOT counts (granular/unified/read-modes) und bietet **globales Search/Filter** über alle Tool-Tabellen.
  - Pillar-Tool-Views haben ebenfalls **Search/Filter** (Name/Description).
  - Tool-Detailseiten zeigen jetzt zusätzlich:
    - **Output contract** (aus `generated/tool-enrichments.json`, wo vorhanden)
    - **Implementation links** (GitHub code paths; enrichment-first, sonst Fallback `rust/src/tools/<tool>.rs` wenn vorhanden)
  - Enrichments erweitert (u.a. `ctx_read`, `ctx_shell`, `ctx_search`, `ctx_tree`, `ctx_proof`, `ctx_verify`) um `output_contract` + `code_paths` + zusätzliche Beispiele.
  - Relevant: `worktrees/deploy-ctxos/website/src/page-templates/DocsToolsPage.astro`, `worktrees/deploy-ctxos/website/src/page-templates/DocsToolsPillarPage.astro`, `worktrees/deploy-ctxos/website/src/page-templates/DocsToolDetailPage.astro`, `worktrees/deploy-ctxos/website/generated/tool-enrichments.json`

**Evidence (lokal, minimal)**:
- `cd worktrees/deploy-ctxos/website && npm run -s validate:doc-claims`
- `cd worktrees/deploy-ctxos/website && npm run -s validate:manifest`
- `cd worktrees/deploy-ctxos/website && npm run -s validate:docs-coverage`
- `cd worktrees/deploy-ctxos/website && npm run -s validate:tools`
- `cd worktrees/deploy-ctxos/website && PATH="/opt/homebrew/opt/node@22/bin:$PATH" npm run -s build`

**GitLab Tickets (Context‑OS)**:
- `#2301` Tools Reference IA v2 → closed

### 2026-05-02 — Docs i18n Hardening (EPIC 0: Docs/Website)

- **0.6 Docs i18n Hardening** (`#2302`) — **closed**:
  - `validate-i18n-duplicates.mjs` ist jetzt ein **Gate**: Build schlägt fehl bei **neuen** duplicate key trees (legacy allowlist bleibt warn-only).
  - Neuer dist-basierter, locale-aware **Linkcheck**: `website/scripts/validate-links.mjs`
    - prüft interne `href="/..."` Links in gebautem `dist/` (inkl. Locale-Routen)
    - unterstützt Astro routing (`/x` → `/x/index.html`) + Sonderfall (`/404` → `/404.html`) + Assets
  - Build pipeline hardened: `npm run build` ruft `validate-links.mjs` nach `astro build` und vor `pagefind` auf.
  - Fix: Broken link `/docs/guides/remote-setup` → `/docs/remote-setup` in `DocsGuideDockerPage.astro`.
  - Relevant: `worktrees/deploy-ctxos/website/scripts/validate-links.mjs`, `worktrees/deploy-ctxos/website/scripts/validate-i18n-duplicates.mjs`, `worktrees/deploy-ctxos/website/package.json`, `worktrees/deploy-ctxos/website/src/page-templates/DocsGuideDockerPage.astro`

**Evidence (lokal, minimal)**:
- `cd worktrees/deploy-ctxos/website && npm run -s validate:i18n`
- `cd worktrees/deploy-ctxos/website && npm run -s validate:i18n-dupes`
- `cd worktrees/deploy-ctxos/website && PATH="/opt/homebrew/opt/node@22/bin:$PATH" npm run -s build`

**GitLab Tickets (Context‑OS)**:
- `#2302` Docs i18n Hardening → closed

### 2026-05-02 — HTTP MCP + Team Server Contracts v1 (EPIC 5: Context Delivery)

- **5.1 HTTP MCP Contract v1** (`#2330`) — **closed**:
  - Host check wired as first gate (unless disabled); loopback defaults preserved.
  - Non-loopback bind requires auth token; `/health` always open.
  - Typed JSON error codes across middleware + `/v1/tools/call`.
  - Integration tests (contract-level): health open, manifest auth, host-deny, rate limit typed error.
  - Docs: new page `/docs/http-mcp` (+ locale route) and contract doc `docs/contracts/http-mcp-contract-v1.md`.
  - Relevant: `rust/src/http_server/mod.rs`, `worktrees/deploy-ctxos/website/src/page-templates/DocsHttpMcpPage.astro`

- **5.2 Team Server Contract v1** (`#2331`) — **closed**:
  - Workspace selection contract: `x-leanctx-workspace` header + `workspaceId` body + deterministic fallback.
  - `rewrite_dot_paths` contract clarified and audited behavior kept deterministic.
  - Audit log hardened: JSONL schema documented; arguments stored as canonicalized `argumentsMd5` only (no raw args).
  - Typed errors for auth/scope/workspace + tool timeout/tool error.
  - Integration tests: scope denied (403) + unknown workspace (400) typed errors.
  - Docs: team server page updated + contract doc `docs/contracts/team-server-contract-v1.md`.
  - Relevant: `rust/src/http_server/team.rs`, `worktrees/deploy-ctxos/website/src/page-templates/DocsTeamServerPage.astro`

**Evidence (lokal, minimal)**:
- `cd rust && cargo test --all-features -q http_contract_v1`
- `cd rust && cargo test --all-features -q scope_denied_is_403_with_typed_error`
- `cd rust && cargo test --all-features -q unknown_workspace_is_400_with_typed_error`
- `cd worktrees/deploy-ctxos/website && PATH="/opt/homebrew/opt/node@22/bin:$PATH" npm run -s build`

**GitLab Tickets (Context‑OS)**:
- `#2330` HTTP MCP Contract v1 → closed
- `#2331` Team Server Contract v1 → closed

### 2026-05-02 — SDK + Cookbook E2E Proof Suite (EPIC 5: Context Delivery)

- **5.3 SDK + Cookbook E2E Proof Suite** (`#2332`) — **closed**:
  - SDK surfaces typed HTTP error codes (`error_code`) via `LeanCtxHttpError.errorCode`.
  - Real E2E test spins up a real `lean-ctx serve` (loopback + auth token) and validates:
    - `/health` is reachable
    - `/v1/manifest` requires auth and returns typed `unauthorized`
    - `/v1/tools` returns stable shape
    - `/v1/tools/call` works via SDK (`ctx_read` + toolText)
  - CI: `cookbook` job now consumes the `lean-ctx` binary artifact from `rust_test` and runs SDK tests against the real server (no mocks).
  - Relevant: `cookbook/sdk/src/client.e2e.test.ts`, `cookbook/sdk/src/client.ts`, `cookbook/sdk/src/errors.ts`, `ci/gitlab-ci.yml`

**Evidence (lokal, minimal)**:
- `cd cookbook && PATH="/opt/homebrew/opt/node@22/bin:$PATH" npm test`

### 2026-05-02 — Premium Integrations v1 (Cursor/Claude Code) (EPIC 5: Context Delivery)

- **5.4 Premium Integrations v1** (`#2333`) — **closed**:
  - Neues Health-Check Kommando: `lean-ctx doctor integrations` (Cursor + Claude Code drift checks: MCP config, hooks, rules).
  - Neuer Repair-Path Alias: `lean-ctx install --repair` → non-interactive `setup --fix` (merge-based, idempotent, no deletes).
  - Cursor `~/.cursor/hooks.json` Installer ist jetzt **merge-based** (preserves other hooks/plugins) statt overwrite.
  - `lean-ctx setup --fix` und `lean-ctx doctor --fix` reparieren jetzt auch Agent Hooks (Cursor/Claude/Codex).
  - `lean-ctx init --agent claude --project` erzeugt `.claude/settings.local.json` (project-local PreToolUse hooks).
  - Docs Hardening: Integrations Guide aktualisiert (repair + health checks, keine placeholder tool lists); Tool-count drift (55) in zentralen Docs/Templates korrigiert; Secret-scan drift fix im HTTP MCP Contract Doc.
  - Relevant: `rust/src/doctor.rs`, `rust/src/cli/dispatch.rs`, `rust/src/cli/init_cmd.rs`, `rust/src/hooks/agents/cursor.rs`, `worktrees/deploy-ctxos/website/src/page-templates/DocsGuideEditorsPage.astro`, `docs/contracts/http-mcp-contract-v1.md`

**Evidence (lokal, minimal)**:
- `cd rust && cargo test --all-features -q cursor_hooks_merge_preserves_other_entries`
- `cd rust && cargo test --all-features -q docs_tool_counts_match_manifest`
- `cd rust && cargo test --all-features -q secret_scan_artifacts`

### 2026-05-02 — Integrations Autotuning (ALL IDEs): Constraints Matrix v1 + CI Gate (Ticket `#2337` / Parent `#2314`)

- **Docs-backed constraints SSOT**:
  - New doc: `docs/integrations/client-constraints-matrix-v1.md` (machine-readable JSON block + cited vendor sources per client).
  - New CI gate: `rust/tests/client_constraints_matrix_up_to_date.rs` ensures the matrix exists, is parseable, is cited (https URLs), and covers all first-class clients.
- **Provider path drift fixes (docs-based)**:
  - Qwen Code uses `~/.qwen/settings.json` (not `~/.qwen/mcp.json`).
  - Amazon Q Developer uses `~/.aws/amazonq/default.json` (legacy `mcp.json` still tolerated for uninstall).
- **Autotuning guardrail**:
  - `autoApprove` is only emitted where vendor docs explicitly document it (currently Cursor + AWS Kiro) to avoid schema drift on other clients.

**Evidence (lokal, minimal)**:
- `cd rust && cargo test --all-features -q client_constraints_matrix_v1_is_complete_and_cited`
- `cd rust && cargo test --all-features -q client_constraints_matrix_matches_runtime_constraints`

### 2026-05-02 — Instruction Compiler v1 (ALL IDEs): deterministic + size-bounded (Ticket `#2338` / Parent `#2314`)

- New runtime SSOT for client constraints: `rust/src/core/client_constraints.rs` (instruction cap + autoApprove support).
- New instruction compiler: `rust/src/core/instruction_compiler.rs`
  - Deterministic output for same inputs (profile + client + flags).
  - Enforces documented caps (Claude Code: 2048 chars for MCP `instructions`).
- New CLI:
  - `lean-ctx instructions --client <id> --profile <name> [--crp off|compact|tdd] [--unified] [--json] [--include-rules]`
  - `lean-ctx instructions --list-clients`
- Drift gate hardening: matrix doc is now checked against runtime caps/autoApprove (`rust/tests/client_constraints_matrix_up_to_date.rs`).

**Evidence (lokal, minimal)**:
- `cd rust && cargo test --all-features -q`
- `cd rust && cargo run -q --bin lean-ctx -- instructions --client claude-code --profile exploration --json`

### 2026-05-02 — Contract Versioning Policy v1 + Compatibility Matrix (EPIC 5: Context Delivery)

- **5.7 Contract Versioning Policy v1** (`#2336`) — **closed**:
  - Root SSOT doc: `CONTRACTS.md` (policy + machine-checked version KV block + compatibility matrix).
  - Runtime versions centralized in `rust/src/core/contracts.rs` and used by schema emitters.
  - CI gate: `rust/tests/contracts_md_up_to_date.rs` prevents drift between runtime versions and `CONTRACTS.md`.
  - Docs: new delivery reference page `/docs/contracts` (root + locale) linking policy + compatibility view.
  - Relevant: `CONTRACTS.md`, `rust/src/core/contracts.rs`, `rust/src/core/mcp_manifest.rs`, `rust/src/core/context_proof.rs`, `rust/src/core/verification_observability.rs`, `worktrees/deploy-ctxos/website/src/page-templates/DocsContractVersioningPage.astro`

**Evidence (lokal, minimal)**:
- `cd rust && cargo test --all-features -q contracts_md_versions_match_runtime`
- `cd worktrees/deploy-ctxos/website && PATH="/opt/homebrew/opt/node@22/bin:$PATH" npm run -s build`

## EPIC P — PR Context Packs (`lean-ctx pack --pr`)

**Status**: Completed  
**Goal**: One command delivers branch-/diff-aware context (changed files, impact, related tests, relevant artifacts, optional hybrid search results).

**GitLab Epic**: `#95`  
**GitLab Subtickets**: `#104`–`#108`  

| Subticket | Description | Status |
|-----------|-------------|--------|
| P1 | Pack format + output contract (`--format markdown\|json`) | Done |
| P2 | Diff/PR input sources (`git diff`, `--base`, `--diff-from-stdin`) | Done |
| P3 | Context assembly pipeline (reuse `ctx_review`, `ctx_impact`, `ctx_graph`) | Done |
| P4 | MCP tool `ctx_pack` + CLI `lean-ctx pack --pr [--base main]` | Done |
| P5 | Demo + proof (tape/GIF) | Done |

**Entrypoints**:
- **CLI**: `lean-ctx pack --pr [--base <ref>] [--json] [--depth <n>] [--diff-from-stdin]`
- **MCP**: `ctx_pack { action:\"pr\", base, format, depth, diff, project_root }`

---

## EPIC A — Codebase Index 1.0

**Status**: Completed  
**Goal**: Reliable index build, update, resume, and status observation — like SocratiCode but local-first.

**GitLab Epic**: `#96`  
**GitLab Subtickets**: `#109`–`#111`  

| Subticket | Description | Status |
|-----------|-------------|--------|
| A1 | BM25 incremental (content hash, no full rebuild, remove 2000-file limit) | Done |
| A2 | Index status contract (public tool) | Done |
| A3 | File watcher + debounce + recovery + cross-process guard | Done |

**Key files**: `rust/src/core/vector_index.rs`, `rust/src/core/index_orchestrator.rs`

**CLI**: `lean-ctx index status|build|build-full|watch` (wired in `rust/src/cli/dispatch.rs` → `rust/src/cli/index_cmd.rs`)  
**MCP**: `ctx_index { action:\"status\"|\"build\"|\"build-full\", project_root }`  

---

## EPIC B — Hybrid Search 2.0

**Status**: Completed  
**Goal**: Single query delivers best results (lexical + semantic), optionally across multiple repos.

**GitLab Epic**: `#97`  
**GitLab Subtickets**: `#112`–`#113`  

| Subticket | Description | Status |
|-----------|-------------|--------|
| B1 | Hybrid search as first-class workflow (`hybrid\|dense\|bm25` modes, tree-sitter chunk boundaries) | Done |
| B2 | Linked projects / workspace search (`.lean-ctx.json` `linkedProjects`, cross-repo RRF fusion) | Done |

**Key files**: `rust/src/core/hybrid_search.rs`, `rust/src/tools/ctx_semantic_search.rs`

---

## EPIC C — Context Artifacts

**Status**: Completed  
**Goal**: Non-code knowledge (schemas, OpenAPI, infra, architecture docs) is searchable and packable just like code.

**GitLab Epic**: `#98`  
**GitLab Subtickets**: `#114`–`#116`  

| Subticket | Description | Status |
|-----------|-------------|--------|
| C1 | Artifact registry (`.lean-ctx-artifacts.json`) | Done |
| C2 | Artifact index + staleness detection + incremental update | Done |
| C3 | Artifact tools (`ctx_artifacts` actions + integration into search/pack) | Done |

**Key files**: `rust/src/core/context_artifacts.rs`, `rust/src/core/artifact_index.rs`

**Entrypoints**:
- **MCP**: `ctx_artifacts` actions `list|status|index|reindex|search|remove`
- **Integration**: `ctx_pack` includes relevant artifacts; `ctx_semantic_search` supports workspace and artifact-related flows

---

## EPIC D — Stable Project IDs + Branch-Aware

**Status**: Completed  
**Goal**: Indexes are worktree-/clone-stable; optionally branch-aware for CI/PR.

**GitLab Epic**: `#99`  
**GitLab Subtickets**: `#117`–`#118`  

| Subticket | Description | Status |
|-----------|-------------|--------|
| D1 | `project_identity` as index key + auto-migration from legacy path-hash dirs | Done |
| D2 | Branch-aware switch (`LEANCTX_INDEX_BRANCH_AWARE=true`) | Done |

**Key files**: `rust/src/core/project_hash.rs`

---

## EPIC E — Optional Qdrant Backend

**Status**: Completed  
**Goal**: Scaling & team server can use Qdrant without breaking default single-binary DNA.

**GitLab Epic**: `#100`  
**GitLab Subtickets**: `#119`–`#120`  

| Subticket | Description | Status |
|-----------|-------------|--------|
| E1 | Storage abstraction (`core::dense_backend`: local vs qdrant behind feature flag) | Done |
| E2 | Config + telemetry safety (URL, API key, namespace hashing, audit records) | Done |

**Key files**: `rust/src/core/qdrant_store.rs`, `rust/src/core/dense_backend.rs`

---

## EPIC F — Self-Hosted Team Server

**Status**: Completed  
**Commit**: `1a802efcd`  
**Goal**: Shared index + artifacts + graph without managed cloud.

**GitLab Epic**: `#101`  
**GitLab Subtickets**: `#121`–`#123`  

| Subticket | Description | Status |
|-----------|-------------|--------|
| F1 | Server mode architecture (reuse `lean-ctx serve` Streamable HTTP MCP) | Done |
| F2 | AuthN/AuthZ (scoped API tokens: search/graph/artifacts/index, audit log JSONL) | Done |
| F3 | Multi-repo org setup (workspace management, `lean-ctx team sync`) | Done |

**Key files**: `rust/src/http_server/team.rs`, `rust/src/cli/dispatch.rs`  
**CLI**: `lean-ctx team serve`, `lean-ctx team token create`, `lean-ctx team sync`

---

## EPIC G — Interactive Graph Explorer

**Status**: Completed  
**Commit**: `1a802efcd`  
**Goal**: "Show me the graph" is one command, shareable.

**GitLab Epic**: `#102`  
**GitLab Subticket**: `#124`  

| Subticket | Description | Status |
|-----------|-------------|--------|
| G1 | Self-contained HTML export with pan/zoom, node selection, transitive highlighting, PNG export | Done |

**Key files**: `rust/src/core/graph_export.rs`  
**CLI**: `lean-ctx graph export-html`  
**MCP**: `ctx_graph action=export-html`

---

## EPIC H — Verification: Benchmarks, Tests, Security

**Status**: Completed  
**Commits**: `1a802efcd`, `26be098d6`

**GitLab Epic**: `#103`  
**GitLab Subtickets**: `#125`–`#127`  

| Subticket | Description | Status |
|-----------|-------------|--------|
| H1 | Real-world benchmark suite (grep vs `ctx_semantic_search` + `ctx_graph/impact`) | Done |
| H2 | Regression tests (incremental index, watcher, linkedProjects RRF, artifact search) | Done |
| H3 | Security hardening (pathjail for artifacts/linkedProjects, rate limits in team server) | Done |

**Key files**: `rust/src/core/workspace_config.rs` (pathjail integration)

---

## Context OS — Phase 2 (Infrastruktur-Standardisierung) — Execution Log

### 2026-05-02 — Context IR v1 + Pipeline Unification (metrics-only first)

**Ziel**: Ein einheitliches, versioniertes IR für alle I/O Quellen (read/shell/search/provider), plus per-layer Metrics Export — ohne Big-Bang Refactor.

- **ContextIrV1 (bounded + redaction-safe)**:
  - Neues Schema + persistenter Store: `rust/src/core/context_ir.rs`
  - Contract SSOT: `rust/src/core/contracts.rs` + `CONTRACTS.md`
  - Contract doc: `docs/contracts/context-ir-v1.md`
- **Inkrementelle Collection (kein Behavior-Drift)**:
  - `ctx_read`: IR + Pipeline-Metrics (Compression-layer) beim Read-Dispatch
  - `ctx_shell` + `ctx_search`: IR + Pipeline-Metrics (Compression-layer) beim Dispatch
- **Proof Export referenziert IR**:
  - `lean-ctx proof` exportiert zusätzlich `context-ir-v1_<timestamp>.json` nach `project/.lean-ctx/proofs/`

**Evidence (lokal)**:
- `cd rust && cargo test --all-features`
- `cd rust && cargo clippy --all-features -- -D warnings`

**GitLab Tickets (Context‑OS)**:
- `#2308` Context IR v1 + Pipeline Unification → closed

### 2026-05-02 — Intent→Mode→Budget Router v1 (Policy Contract)

**Ziel**: Routing als testbarer Policy Contract (statt nur Heuristik): Intent → Model Tier Empfehlung + Read-Mode Empfehlung + deterministische Degradation unter Budget/Pressure.

- **IntentRouteV1 Contract + Policy**:
  - Router Schema + deterministische Reasoning-Fields: `rust/src/core/intent_router.rs`
  - Profile Overrides: `[routing]` in `rust/src/core/profiles.rs` (z.B. `hotfix` capped auf `fast`)
  - Contract SSOT: `rust/src/core/contracts.rs` + `CONTRACTS.md`
  - Contract doc: `docs/contracts/intent-route-v1.md`
- **Runtime surface**:
  - `ctx_intent` unterstützt `format=json` und liefert `IntentRouteV1` als JSON (ansonsten compact ack)
  - Tool schema aktualisiert: `rust/src/tool_defs/granular.rs`
  - SSOT manifest regeneriert: `rust/bin/gen_mcp_manifest` → `website/generated/mcp-tools.json`

**Evidence (lokal)**:
- `cd rust && cargo test --all-features`
- `cd rust && cargo clippy --all-features -- -D warnings`
- `cd rust && cargo test --test mcp_manifest_up_to_date`
- `cd rust && cargo test --test contracts_md_up_to_date`

**GitLab Tickets (Context‑OS)**:
- `#2309` Intent→Mode→Budget Router v1 → closed

### 2026-05-02 — Budget/SLO Degradation Policy v1 (Warn/Throttle/Block, policy-backed)

**Ziel**: Degradation als versionierter Policy Contract, deterministisch und überall gleich (MCP/HTTP/Team). Default bleibt **warn-only**; Enforcement ist explizit hinter Profile-Config.

- **DegradationPolicyV1 Contract**:
  - Contract + ladder + reason_code: `rust/src/core/degradation_policy.rs`
  - Contract SSOT: `rust/src/core/contracts.rs` + `CONTRACTS.md`
  - Contract doc: `docs/contracts/degradation-policy-v1.md`
- **Enforcement (ein Boundary für alle Surfaces)**:
  - `rust/src/server/mod.rs` (`call_tool`): wendet Policy konsistent an
    - Budget-based Block bleibt role-gated (`block_at_percent < 255`)
    - SLO Throttle/Block wird nur enforced wenn Profile `[degradation].enforce=true`
- **Proof Export**:
  - `lean-ctx proof` schreibt zusätzlich `degradation-policy-v1_<timestamp>.json` nach `project/.lean-ctx/proofs/` (`rust/src/tools/ctx_proof.rs`)

**Evidence (lokal)**:
- `cd rust && cargo test --all-features`
- `cd rust && cargo clippy --all-features -- -D warnings`
- `cd rust && cargo test --test contracts_md_up_to_date`

**GitLab Tickets (Context‑OS)**:
- `#2312` Budget/SLO Degradation Policy v1 → closed

### 2026-05-02 — Workflow Evidence Ledger v1 (tool receipts + proof artifacts + evidence-gated transitions)

**Ziel**: Evidence Inputs standardisieren und auditierbar machen: Tool Receipts + Proof Artefakte + manual Evidence als bounded, content-addressed Ledger; Workflows können Transitions zuverlässig über Evidence Keys gaten.

- **WorkflowEvidenceLedgerV1 Contract**:
  - Contract SSOT: `rust/src/core/contracts.rs` + `CONTRACTS.md`
  - Contract doc: `docs/contracts/workflow-evidence-ledger-v1.md`
  - Runtime: `rust/src/core/evidence_ledger.rs` (bounded store, redaction-safe excerpts, deterministic IDs)
- **Automatic evidence capture**:
  - Tool-call boundary schreibt Tool Receipts in Ledger: `rust/src/server/mod.rs`
  - `ctx_workflow evidence_add` schreibt manual Evidence in Ledger: `rust/src/tools/ctx_workflow.rs`
  - `lean-ctx proof` schreibt Proof Artefakte als Evidence (`proof:*` Keys): `rust/src/tools/ctx_proof.rs`

**Evidence (lokal)**:
- `cd rust && cargo test --all-features`
- `cd rust && cargo clippy --all-features -- -D warnings`
- `cd rust && cargo test --test contracts_md_up_to_date`
- `cd rust && cargo test --test mcp_manifest_up_to_date`

**GitLab Tickets (Context‑OS)**:
- `#2315` Workflow Evidence Ledger v1 → closed

### 2026-05-02 — Autonomy Drivers v1 (preload/prefetch/dedup/response) als state machine + proofs

**Ziel**: Deterministische Helper‑Driver (kein “full autonomy”), die guarded (Budget/SLO/Boundary) laufen und als Proof/Report exportierbar sind: **welche Driver liefen + warum**.

- **AutonomyDriversV1 Contract + Store (bounded, redaction-safe)**:
  - Contract SSOT: `rust/src/core/contracts.rs` + `CONTRACTS.md`
  - Contract doc: `docs/contracts/autonomy-drivers-v1.md`
  - Runtime store: `rust/src/core/autonomy_drivers.rs` (`~/.lean-ctx/autonomy_drivers_v1.json`)
- **Deterministischer Driver Planner + Guards**:
  - Profile-gated (opt-in): `rust/src/core/profiles.rs` (`[autonomy]`, neues built-in Profil `coder`)
  - Budget/SLO guard via `DegradationPolicyV1` (Throttle/Block → skip)
  - Boundary: alle file reads laufen über `io_boundary::jail_and_check_path` (skip secret-like paths)
- **Wiring (Pipeline + Output Metadata + Proofs)**:
  - Session start: auto preload/overview pre-hook (`rust/src/tools/autonomy.rs`), emits bounded driver report
  - After read: optional bounded prefetch + dedup (opt-in) (`rust/src/tools/autonomy.rs`)
  - Post call: optional response shaping für große Outputs (`rust/src/tools/autonomy.rs` + `rust/src/server/mod.rs`), **nie** für JSON outputs
  - Pipeline: neue Layer-Kind `autonomy` + metrics record bei response shaping (`rust/src/core/pipeline.rs`, `rust/src/server/mod.rs`)
  - Proof export: `lean-ctx proof` schreibt zusätzlich `autonomy-drivers-v1_<timestamp>.json` nach `project/.lean-ctx/proofs/` (`rust/src/tools/ctx_proof.rs`)
  - Evidence: Proof-Artefakt wird als `proof:autonomy-drivers-v1` ins Evidence Ledger recorded
- **Security Fixes**:
  - `ctx_preload` + `ctx_prefetch` jailed reads (kein Path traversal / kein secret-like preload)

**Evidence (lokal)**:
- `cd rust && cargo fmt`
- `cd rust && cargo test --all-features -q`
- `cd rust && cargo clippy --all-features -- -D warnings`
- `cd rust && cargo test -q --test contracts_md_up_to_date`
- `cd rust && cargo test -q --test mcp_manifest_up_to_date`

**GitLab Tickets (Context‑OS)**:
- `#2313` Autonomy Drivers v1 → closed

### 2026-05-03 — Tokenizer-aware Translation Driver v1 (TokenOptimizer calibrated per model family)

**Ziel**: Translation wird tokenizer-aware und modell-/profile-gesteuert, ohne Default-Format-Breaking-Changes: Unicode→ASCII nur bei opt-in + deterministischer Auswahl.

- **TokenizerTranslationDriverV1 Contract + SSOT**:
  - Contract SSOT: `rust/src/core/contracts.rs` + `CONTRACTS.md`
  - Contract doc: `docs/contracts/tokenizer-translation-driver-v1.md`
  - Runtime: `rust/src/core/tokenizer_translation_driver.rs`
- **Policy (safe defaults, opt-in)**:
  - Neues Profile-Segment: `translation.enabled` + `translation.ruleset = legacy|ascii|auto` (`rust/src/core/profiles.rs`)
  - Built-in Profil `coder` nutzt `translation.enabled=true` + `ruleset=auto`
- **Deterministische Ruleset Selection**:
  - `LEAN_CTX_MODEL` / `LCTX_MODEL` → model_key → ruleset (`auto`: OpenAI/GPT → ASCII, sonst legacy)
  - JSON Outputs werden **nie** übersetzt (machine-readable bleibt exakt)
- **Wiring + Verifier Safety**:
  - Tool-call boundary wendet Translation an (nur wenn enabled) + Pipeline Metrics (`LayerKind::Translation`): `rust/src/server/mod.rs`
  - Verifier bleibt Gate: Path/Identifier checks laufen auf “vorher vs nachher” (`rust/src/core/output_verification.rs`)
- **Bench / Measurement**:
  - `ctx_benchmark` zeigt zusätzlich `signatures (tdd, ascii)` token_cost als Vergleich (`rust/src/tools/ctx_benchmark.rs`)
- **Determinism Fix**:
  - `TokenOptimizer` rule application order ist jetzt deterministisch (Vec+sort statt HashMap iteration): `rust/src/core/neural/token_optimizer.rs`

**Evidence (lokal)**:
- `cd rust && cargo fmt`
- `cd rust && cargo test --all-features -q`
- `cd rust && cargo clippy --all-features -- -D warnings`
- `cd rust && cargo test -q --test contracts_md_up_to_date`
- `cd rust && cargo test -q --test mcp_manifest_up_to_date`

**GitLab Tickets (Context‑OS)**:
- `#2310` Tokenizer-aware Translation Driver v1 → closed

### 2026-05-03 — Attention-aware Layout Driver v1 (learned L-curve + context_reorder integration)

**Ziel**: Delivery nutzt attention-aware ordering (semantic chunks first, line-level fallback) als **opt-in** pro Profile; deterministisch (input+keywords) und verifier-safe (nur Umsortierung, kein Drop).

- **AttentionLayoutDriverV1 Contract + SSOT**:
  - Contract SSOT: `rust/src/core/contracts.rs` + `CONTRACTS.md`
  - Contract doc: `docs/contracts/attention-layout-driver-v1.md`
  - Runtime: `rust/src/core/attention_layout_driver.rs`
- **Policy (opt-in)**:
  - Neues Profile-Segment: `layout.enabled` + `layout.min_lines` (`rust/src/core/profiles.rs`)
  - Built-in Profil `review`: `layout.enabled=true` (Default `exploration` bleibt unverändert/off)
- **Determinismus (tie-breaks)**:
  - Line-level reorder: stable sort tie-break via `original_index` (`rust/src/core/neural/context_reorder.rs`)
  - Chunk reorder: stable sort tie-break via `start_line` (`rust/src/core/semantic_chunks.rs`)
- **Wiring (Delivery surface)**:
  - `ctx_read` (full) wendet reorder vor SymbolMap/Header an, **nur** wenn `task` Keywords vorhanden (`rust/src/tools/ctx_read.rs`)
  - Keywords via `task_relevance::parse_task_hints` (task/intent)

**Evidence (lokal)**:
- `cd rust && cargo fmt`
- `cd rust && cargo test --all-features -q`
- `cd rust && cargo clippy --all-features -- -D warnings`
- `cd rust && cargo test -q --test contracts_md_up_to_date`
- `cd rust && cargo test -q --test mcp_manifest_up_to_date`

**GitLab Tickets (Context‑OS)**:
- `#2311` Attention-aware Layout Driver v1 → closed

### 2026-05-03 — CCP Session Bundle v1 (Session Export/Import Contract, redacted-by-default)

**Ziel**: Standardisiertes, replaybares Export/Import-Format für Session-Ausschnitte (Task/Findings/Decisions/Evidence/State) mit **deterministischen IDs**, **Boundedness** (MAX bytes) und **Default-Redaction**.

- **CcpSessionBundleV1 Contract + SSOT**:
  - Contract SSOT: `rust/src/core/contracts.rs` + `CONTRACTS.md`
  - Contract doc: `docs/contracts/ccp-session-bundle-v1.md`
  - Runtime: `rust/src/core/ccp_session_bundle.rs`
- **Tool Surface (`ctx_session`)**:
  - Neue Actions: `export`, `import` (`rust/src/tools/ctx_session.rs`)
  - Dispatcher Options: `format`, `path`, `write`, `privacy` (`rust/src/server/dispatch/session_tools.rs`)
  - Tool schema erweitert (Args + enums): `rust/src/tool_defs/granular.rs`
- **Security/Privacy + Boundedness**:
  - Export/Import via `io_boundary::jail_and_check_path` (kein Path traversal / keine secret-like locations)
  - Default `privacy=redacted`; `privacy=full` nur für `admin` Role
  - Size Cap: `MAX_BUNDLE_BYTES` enforced bei serialize/read
  - Import markiert `files_touched[*].stale=true` wenn Pfade fehlen/außerhalb Jail; warnt bei `project_identity_hash` mismatch
- **Compatibility (Session State)**:
  - `FileTouched.stale` mit `#[serde(default)]` → alte Sessions bleiben loadbar (`rust/src/core/session.rs`)

**Evidence (lokal)**:
- `cd rust && cargo fmt`
- `cd rust && cargo test --all-features`
- `cd rust && cargo clippy --all-features -- -D warnings`

**GitLab Tickets (Context‑OS)**:
- `#2316` CCP Session Bundle v1 → closed

### 2026-05-03 — Knowledge Policy Contract v1 (bounded governance, budgets, profile overrides)

**Ziel**: Versionierter Policy-Vertrag für Knowledge (Facts/Patterns/History + Relations), der **bounded**, **deterministisch**, **replayable** und **auditable** ist.

- **KnowledgePolicy Contract + SSOT**:
  - Contract SSOT: `rust/src/core/contracts.rs` + `CONTRACTS.md`
  - Contract doc: `docs/contracts/knowledge-policy-contract-v1.md`
  - Runtime: `rust/src/core/memory_policy.rs` + `rust/src/core/knowledge.rs`
- **Policy Surface (Config + Profile Overrides)**:
  - `KnowledgePolicy` Budgets: `recall_facts_limit`, `rooms_limit`, `timeline_limit`, `relations_limit`
  - Profile Overrides: `Profile.memory` (Option-Overrides) + deterministic merge (`rust/src/core/profiles.rs`)
  - Effective policy load+validate (inkl. overrides) in Tools (`rust/src/tools/ctx_knowledge.rs`, `rust/src/tools/ctx_knowledge_relations.rs`)
- **Semantik (stabil, deterministisch)**:
  - Contradiction severity: High/Medium/Low (threshold + confirmations)
  - Similarity guard verhindert false contradictions bei semantisch gleichen Werten
  - Supersedes chain: archived→current via deterministische `fact_version_id_v1` (MD5)
- **Tool Surface**:
  - `ctx_knowledge action=policy value=show|validate` (effective policy + range validation)
  - Budgets enforced für `recall`/`rooms`/`timeline`/`relations` (stable ordering + truncation)

**Evidence (lokal)**:
- `cd rust && cargo fmt`
- `cd rust && cargo test --all-features -q`
- `cd rust && cargo clippy --all-features -- -D warnings`
- `cd rust && cargo test -q --test contracts_md_up_to_date`
- `cd rust && cargo test -q --test mcp_manifest_up_to_date`

**GitLab Tickets (Context‑OS)**:
- `#2317` Knowledge Policy Contract v1 → closed

### 2026-05-03 — Graph Reproducibility Contract v1 (format=json + freshness + architecture proof artifacts)

**Ziel**: Graph-Tools (Property Graph) werden **reproducible** (CI/Proofs), **deterministisch** (stable ordering), **bounded** (Output caps) und liefern maschinenlesbare Exporte.

- **Graph Reproducibility Contract + SSOT**:
  - Contract SSOT: `rust/src/core/contracts.rs` + `CONTRACTS.md`
  - Contract doc: `docs/contracts/graph-reproducibility-contract-v1.md`
- **Runtime (Determinismus + Freshness)**:
  - Property graph meta: `.lean-ctx/graph.meta.json` (`rust/src/core/property_graph/meta.rs`)
  - Deterministische Adjacency + stable BFS/DFS: `rust/src/core/property_graph/queries.rs`
  - Deterministischer Build (sorted file enumeration + sorted import targets): `rust/src/tools/ctx_impact.rs`
  - Deterministische Architecture Outputs + bounded previews: `rust/src/tools/ctx_architecture.rs`
- **Tool Surface (`format=json`)**:
  - `ctx_impact`: `analyze|chain|build|status` + `format=text|json` (inkl. `project_identity_hash`, `graph_meta`, truncation markers)
  - `ctx_architecture`: `overview|clusters|layers|cycles|entrypoints|module` + `format=text|json`
- Tool schemas: `rust/src/tool_defs/granular.rs` + Manifest SSOT regen (`cargo run --example gen_mcp_manifest --features dev-tools`)
- **Proof Artifacts (Architecture Overview)**:
  - `ctx_proof write=true` schreibt zusätzlich:
    - `.lean-ctx/proofs/architecture-overview-v1_<ts>.json`
    - `.lean-ctx/proofs/architecture-overview-v1_<ts>.html`
  - EvidenceLedger keys: `proof:architecture-overview-v1` + `proof:architecture-overview-v1-html`

**Evidence (lokal)**:
- `cd rust && cargo fmt`
- `cd rust && cargo test --all-features -q`
- `cd rust && cargo clippy --all-features -- -D warnings`
- `cd rust && cargo test -q --test contracts_md_up_to_date`
- `cd rust && cargo test -q --test mcp_manifest_up_to_date`
- `cd rust && cargo test -q --all-features --test property_graph_reproducibility_contract`

**GitLab Tickets (Context‑OS)**:
- `#2318` Graph Reproducibility Contract v1 → closed

### 2026-05-03 — A2A Contract v1 (privacy/TTL + rate limiting + cost attribution + export snapshot)

**Ziel**: A2A primitives (Messages/Tasks/Diaries) werden deterministisch, bounded und privacy-safe; zusätzlich gibt es ein maschinenlesbares Snapshot‑Artefakt für Proofs/Audits.

- **Contract (SSOT)**:
  - `CONTRACTS.md` + runtime versions: `rust/src/core/contracts.rs`
  - Contract doc: `docs/contracts/a2a-contract-v1.md`
- **Messages (Privacy + TTL + Project Scope)**:
  - A2A Semantik: `rust/src/core/a2a/message.rs`
  - Persisted scratchpad: `rust/src/core/agents.rs` (`ScratchpadEntry` erweitert: `privacy`, `priority`, `expires_at`, `project_root`, `metadata`)
  - Enforcement:
    - `privacy=private` erfordert `to_agent`
    - `ttl_hours>=1` ⇒ deterministic expiry cleanup
    - project-scoped visibility (nur matching `project_root`)
- **Tool Surface (`ctx_agent`, `ctx_task`)**:
  - `ctx_agent` erweitert: `privacy`, `priority`, `ttl_hours`, `format`, `write`, `filename`, `action=export` (`rust/src/tools/ctx_agent.rs`)
  - Dispatcher erweitert: `rust/src/server/dispatch/session_tools.rs`
  - `ctx_task` state machine: `rust/src/core/a2a/task.rs` + `rust/src/tools/ctx_task.rs`
- **Rate limiting (fairness)**:
  - token bucket limiter: `rust/src/core/a2a/rate_limiter.rs` (env overrides; `retry_after_ms`)
  - enforced at MCP tool boundary: `rust/src/server/dispatch/mod.rs`
- **Cost attribution (inkl. cached tokens)**:
  - Store + pricing integration: `rust/src/core/a2a/cost_attribution.rs`
  - Reporting: `rust/src/tools/ctx_cost.rs` + `ctx_gain action=cost`
  - Tool-call boundary passes `cached_tokens` when provided: `rust/src/server/mod.rs`
- **Proof artifact (A2A Snapshot v1)**:
  - `ctx_agent action=export write=true` schreibt `.lean-ctx/proofs/a2a-snapshot-v1_<ts>.json`
  - EvidenceLedger key: `proof:a2a-snapshot-v1`

**Evidence (lokal)**:
- `cd rust && cargo fmt`
- `cd rust && cargo test --all-features -q`
- `cd rust && cargo clippy --all-features -- -D warnings`
- `cd rust && cargo test -q --test contracts_md_up_to_date`
- `cd rust && cargo test -q --test mcp_manifest_up_to_date`

**GitLab Tickets (Context‑OS)**:
- `#2319` A2A Contract v1 → closed

---

## Additional Fixes (v3.4.7 Release Cycle)

### GitHub Issues

| Issue | Title | Fix | Commit |
|-------|-------|-----|--------|
| #173 | Pi MCP bridge sends `paths` as JSON-encoded string | `get_str_array` handles both native arrays and JSON-encoded strings | `1a802efcd` |
| #174 | `ctx_discover_tools` not invocable with static-registry clients | New `ctx_call` meta-tool in `CORE_TOOL_NAMES` | `1a802efcd` |

### Discord Bug Reports

| Bug | Reporter | Root Cause | Fix | Commit |
|-----|----------|------------|-----|--------|
| Pipe guard false positive on Windows Git Bash | knindza94 | `rc_has_pipe_guard` only checked legacy paths, not XDG; backslashes not handled | `doctor.rs` + `shell_init.rs` refactored with stable begin/end markers, bash-compatible path conversion | `46f3996ce` |
| Claude Code hooks not intercepting | knindza94 | `extract_json_field` failed on spaced JSON; hook install overwrote other plugins | Robust JSON parsing + merge-based `ensure_command_hook` | `b432518ab`, `4672fce86` |

### IDE Integration Audit

| Change | Files | Commit |
|--------|-------|--------|
| Dual-format hook output (Cursor + Claude Code compatible) | `hook_handlers.rs` | `31dbf8229` |
| JetBrains `mcpServers` snippet format | `writers.rs`, `jetbrains.rs` | `86d329924` |

**Verified IDEs**: Cursor, VS Code, Claude Code, JetBrains, Codex, OpenCode, Gemini CLI

---

## Release v3.4.7

**Tag**: `v3.4.7` | **Date**: 2026-05-01 | **Workflow**: `#25227853872` (11/11 green)

| Channel | Version | Status |
|---------|---------|--------|
| GitHub Release | v3.4.7 (9 assets) | Published |
| crates.io | 3.4.7 | Published |
| npm lean-ctx-bin | 3.4.7 | Published |
| npm pi-lean-ctx | 3.4.7 | Published |
| Homebrew | 3.4.7 (auto-updated) | Published |
| AUR lean-ctx | 3.4.7 | Pushed |
| AUR lean-ctx-bin | 3.4.7 | Pushed |
| leanctx.com | version.txt → 3.4.7 | Deployed |
| GitLab mirror | main synced | Pushed |