# Cheritto — History

## Core Context

- **Project:** A Windows COM interop MCP server and CLI for programmatic Excel automation with 25 tools and 225 operations.
- **Role:** Platform Dev
- **Joined:** 2026-03-15T10:42:22.620Z

## Learnings

<!-- Append learnings below -->
- 2026-05-13: Daemon lifecycle hardening should coordinate on real readiness, not process spawn. The startup mutex now spans the full ping-ready window so concurrent starters wait for a responsive daemon or a clear startup failure instead of relying on bounded retry mitigation.
- 2026-05-13: CLI daemon shutdown must be response-safe and drain-aware. `service.shutdown` now requests shutdown after the RPC response is returned, the pipe server stops accepting new clients, active connection tasks are tracked/drained, and the WinForms host waits for service completion before disposing.
- 2026-05-13: Session close truthfulness depends on surfacing teardown failures. `SessionManager.CloseSession` no longer converts `Dispose()` failures into success, and service-layer session operations now use `BeginOperation`/`EndOperation` so close validation can see in-flight work.
- 2026-05-13: Default-pipe daemon readiness must include host initialization, not just pipe ping. Start the RPC pipe only after WinForms/tray host setup succeeds, and have CLI clients explicitly monitor named-pipe disconnects so daemon exits surface promptly instead of waiting for the full command timeout.
- 2026-04-27: Plugin publish wiring must actively strip committed runtime payloads (`.exe`, `.dll`, `.deps.json`, `.runtimeconfig.json`) after copying marketplace templates. That keeps `mcp-server-excel-plugins` wrapper/bootstrap-only even if an older published template repo still contains runtime files.
- 2026-04-27: Source-owned overlay copy helpers for plugin publishing need `Get-ChildItem -Force`; otherwise hidden bootstrap assets such as dotfiles can silently drop out of the published plugin bundle.
- 2026-04-25: The published Copilot marketplace repo cannot accept the self-contained `excelcli.exe` bundle once it crosses GitHub's file-size limit (observed at ~175 MB, rejected with `GH001`). The durable fix is to keep `excel-cli` as a skill-only plugin and leave CLI binary distribution to the main GitHub release ZIP / NuGet channels.
- 2026-04-25: In GitHub Actions PowerShell steps, handling an expected native exit code is a two-part fix: capture the code with `PSNativeCommandUseErrorActionPreference = $false`, then clear `$LASTEXITCODE` before the step ends if that non-zero code was expected. Otherwise the step can still fail even after your script branches correctly.
- 2026-04-25: In GitHub Actions PowerShell steps, `git diff --quiet` is not safe as a bare `if (...)` condition when a diff is expected. Treat exit code `1` as data, not failure: temporarily disable `PSNativeCommandUseErrorActionPreference`, capture `$LASTEXITCODE`, then branch on `0` (no changes) vs `1` (changes present).
- 2026-04-25: A failed Dependabot security update on `vscode-extension` can be a real repo issue without a usable upstream patch path. In this case `@vscode/vsce` 3.x pulled `@azure/msal-node -> uuid@^8.3.0`, so the practical fix was to validate Dependabot's suggested `@vscode/vsce` 2.25.0 downgrade, then confirm `npm audit` and the exact `npm run package` release path still pass before merging.
- 2026-04-25: `publish-plugins.yml` must resolve source release tags from a fetched git checkout (`git tag --points-at workflow_run.head_sha`), not from the REST `matching-refs` payload. Release tags here are annotated, so `.object.sha` is the tag object SHA, not the released commit SHA; the old lookup caused the follow-on publish workflow to fail immediately after a successful release.
- 2026-04-25: The retired Azure runner workflow files were safe to delete once the docs stopped telling people to rename `.disabled` files back into service. Minimal cleanup was enough: remove the two disabled workflow files, update the workflow instructions, and reframe the Azure runner guide as historical infrastructure reference.
- 2026-03-16: Bug 3 is already supported under `range.set-number-format`; the actual gap is that the formatting surface is split between `range` (display formats) and `range_format` (visual styling), and top-level feature tables currently hide that split.
- 2026-03-16: Bug 5 is already supported under `range_format.auto-fit-columns` / `auto-fit-rows`; the main weakness is discoverability, not backend capability.
- 2026-03-16: Bug 4 is a real surface gap. A `List<...>` batch request is consistent with existing patterns such as `IRangeEditCommands.Sort(... List<SortColumn> ...)`, so the likely risk is in API review and docs parity, not generator feasibility.
- 2026-03-21: Stability bug (v1.8.32) isolates to CLI/daemon/service wrapper layer. Pure ComInterop session tests pass (Nate's serial workflow coverage), but CLI-through-daemon pathway lacks regression tests for serial PQ refresh → timeout → session recovery → new file open workflows. Test gap: no CLI integration tests exist for multi-step PQ refresh sequences that mirror the bug report's excelcli serial command pattern.
- 2026-03-21: **PIVOT DECISION REACHED.** Serial workflow control tests all GREEN confirms ComInterop/session timeout layer is correct. Any remaining bug lives in CLI daemon state, service routing, or workbook patterns. New mission: trace CLI/service/session wrapper seam for bug survival — identify where command routing, session wiring, or parameter propagation can fail without showing up in synthetic Core-layer regression tests.
- 2026-03-21: **Investigation Complete — Test Gap Documented.** Traced CLI-daemon-service seam and confirmed zero existing integration tests for serial Power Query workflows via CLI subprocess pattern. ComInterop control tests PASSED (7/7) — confirms pure batch/session layer stable. Created test pattern recommendations for `PowerQueryWorkflowTests.cs` with `CliProcessHelper` + `ServiceFixture` + workbook fixture for future regression testing. Identified specific wrapper-layer suspects: service RPC cancellation propagation, daemon session cleanup lazy evaluation, CLI process spawn → daemon connection continuity, and idle session monitor interference. **Recommendation: Keep test infrastructure ready, use recommended test pattern if future bug reports provide user workbook or specific workflows.**
- 2026-03-26: **Claude Desktop Release Artifact Discovered.** MCPB (MCP Bundle) is the shipped artifact for Claude Desktop: a ZIP file with .mcpb extension containing manifest.json + icon + README + LICENSE + CHANGELOG + server/excel-mcp-server.exe (self-contained binary). Built by `mcpb/Build-McpBundle.ps1` script; released via `release.yml` Job 4 (build-mcpb) and Job 9 (create-release, uploads to GitHub Releases). Manifest declares compatibility: "claude_desktop": ">=0.10.0", platforms: ["win32"]. Installation: double-click .mcpb file in Claude Desktop. Source: `src/ExcelMcp.McpServer` is published as win-x64 self-contained exe (~50 MB), no trimming, no ReadyToRun (keeps size <15 MB). No agent skills bundled in MCPB (Claude Desktop doesn't use them; skills are VS Code only via chatSkills contribution). MCP Registry entry: server.json declares NuGet package distribution at `packages[0].identifier = Sbroenne.ExcelMcp.McpServer`.
- 2026-03-31: Issue #585 is GREEN at current HEAD in direct MCP and CLI flows. Added focused regressions proving `range_format(action: format-range)` accepts the issue payload via MCP and the equivalent CLI path succeeds when the CLI uses `session create` for new files and the live `sheet create` command name (not `worksheet`).
- 2026-03-31: **Claude Desktop Repro Investigation Complete.** MCPB (.mcpb file, ~50 MB self-contained .NET 10 win-x64 exe) is the shipped Claude Desktop artifact built by `release.yml` Job 4. Installation is one-click (double-click .mcpb → Claude Desktop auto-extracts). This machine has Claude Desktop running (v1.1.9669.0). MCP logs at `$env:APPDATA\Claude\logs\mcp-server-Excel (Windows).log` capture full JSON-RPC protocol (can trace payload and errors). **Repro is FEASIBLE**: Download latest .mcpb from GitHub Releases, double-click, request 14-column range format in chat, inspect MCP log for success/failure. **Automation barrier**: Claude Desktop UI is not controllable via CLI/PowerShell (no REST API, no WebDriver), but server binary invocation + direct JSON-RPC is possible. Decision written to `.squad/decisions/inbox/cheritto-claude-repro.md` with step-by-step instructions and logging guidance.
- 2026-04-01: Worksheet rename parity bug traced to the hand-written MCP tool, not Core or CLI. `ExcelWorksheetTool` exposed rename as `sheet_name` + `target_name`, while the generated CLI and Core contract already used `old_name` + `new_name`; fix is to expose the canonical rename params in MCP and keep the old pair as backward-compatible aliases only.
- 2026-04-01: Hand-written MCP tools need explicit parameter-level `[Description(...)]` metadata when multiple workflows share one method signature. Runtime alias support alone is not enough for LLM clients: without per-parameter schema descriptions, `worksheet` create vs rename vs copy vs copy-to-file remains ambiguous even when the underlying routing is correct.
- 2026-04-02: **PR Prep: Dependency Refresh + pytest-skill-engineering Migration.** Branch is clean, 51 files modified, no untracked infrastructure. Core change: pytest-aitest → pytest-skill-engineering (0.5.9) with new `CopilotEval` fixture replacing old `Agent`/`MCPServer`/`CLIServer` fixtures. Migration is comprehensive — all 41 test files refactored to new fixture API, conftest rewired for skill directories, new `cli_mcp_server.py` wrapper for CLI stdio protocol. .NET deps bump to Microsoft.Extensions 10.0.5, MCP SDK 1.2.0, Roslyn 5.3.0, MSBuild 18.4.0. CHANGELOG unchanged (no new user-facing features). No squad/history/skill changes in PR scope — those stay out. Worksheet.md skill doc updated for rename param clarification (in-scope: extends #588 rename fix). Spec and instruction updates are in-scope: testing-strategy reflects new LLM test philosophy, llm-testing-philosophy codifies "test the product not the LLM" rule. BLOCKER identified: vscode-extension package.json/package-lock.json changes are NOT dependency refresh — those are unrelated editor config changes (tsconfig strict mode). Must exclude from PR or justify why editor config belongs in a dependency-only PR.
- 2026-04-06: **Dependency Refresh Pre-Test Prep.** Refreshed llm-tests Python dependencies via `uv lock --upgrade` (16 packages updated: anyio 4.12.1→4.13.0, attrs 25.4.0→26.1.0, azure-core 1.38.0→1.39.0, azure-identity 1.25.2→1.25.3, certifi 2026.1.4→2026.2.25, charset-normalizer 3.4.4→3.4.6, msal 1.34.0→1.35.1, packaging 25.0→26.0, pydantic-settings 2.12.0→2.13.1, pyjwt 2.12.0→2.12.1, python-dotenv 1.2.1→1.2.2, referencing 0.36.2→0.37.0, requests 2.33.0→2.33.1, sse-starlette 3.2.0→3.3.4, starlette 0.52.1→1.0.0, uvicorn 0.40.0→0.42.0). pytest-skill-engineering remains at 0.5.9 (already current). .NET deps NOT updated: Microsoft.ApplicationInsights.WorkerService 2.23.0→3.0.0 available but is MAJOR breaking change (OpenTelemetry rewrite, InstrumentationKey→ConnectionString, incompatible with Azure Functions scenarios) — requires migration project, not safe for this PR. All other .NET packages current. Worktree ready for Nate's test run: `uv sync` completed, pytest collection verified (58 tests), explicit timeout set (`PYTEST_TIMEOUT=30`). Changes local only (uv.lock modified, not committed).
- 2026-04-27: **PR #620 Merged.** Created and merged PR #620 (`feature/gh-pages-hero-plugin-install-fix` → `main`) via squash. Title: `docs(gh-pages): add Copilot CLI Plugin install button to hero grid`. Merge commit: `c8f5f0c71274781a38c57a4fda8a2047fd631fa4`. Task complete.
- 2026-04-01: **Orchestration Logging Session.** Scribe role: documented Cheritto dependency refresh phase and Nate test execution phase in `orchestration-log/2026-04-01T09-48-22-{agent}.md`. Scribe also created session log for LLM test run at `log/2026-04-01T09-48-22-llm-test-run.md` with test results summary and test-tiering recommendations.

- 2026-04-01: **MCP LLM Test Failures - Investigation Summary.** Analyzed LLM test workflow failures from MCP/tool harness perspective. Key findings: (1) Chart positioning timeout (600s) is test harness configuration, not product - MCP server doesn't control pytest timeout policy. (2) Multiple test files have incomplete implementations - tests define agent and prompt but never call copilot_eval() or define assertion logic (e.g., test_mcp_targetrange_no_skill line 49 asserts on undefined 'result' variable). (3) Calculation mode tests expect LLM to autonomously discover/use calculation_mode tool, but test assertions check for tool usage, not workflow success. (4) Test pattern issues are harness/test-authoring bugs, not MCP schema gaps - the tests themselves are structurally incomplete (missing async call + result assignment). Real MCP contract gaps would manifest as schema errors or tool call failures in logs, not Python syntax/logic errors. Recommendation: Fix test implementations before evaluating MCP discoverability - can't assess tool guidance when tests don't execute properly.

- 2026-04-06: **Calculation Mode Discoverability Fix (MCP Server Instructions).** Found and fixed discrepancy between Program.cs ServerInstructions and skill documentation for calculation_mode tool. Program.cs said "When a task mentions manual/automatic calculation" (too restrictive - requires explicit mention), while SKILL.md correctly says "Use for bulk write performance optimization (10+ cells)". Updated ServerInstructions to match skill: "Use calculation_mode for bulk write operations (10+ cells with values or formulas)" + workflow explanation. This aligns MCP server guidance with skill's workflow-based discovery pattern. Tool description already correct ("WORKFLOW for batch operations"). CLI skill already correct (Rule 7). Fix is surgical - one guidance alignment, no product code changes, maintains MCP/CLI parity.

- 2026-05-13: **Daemon Lifecycle Synthesis — Structural Unsoundness at Boundary.** Synthesized daemon review from Hanna (COM), Nate (test), and real-world failures. Root cause is NOT in retry logic or timeout tuning. The daemon boundary itself has lifecycle assumptions that don't hold under concurrent load. **Priority Framework:** (P0) Startup treats "spawned" as "ready" — duplicate starters and early clean exits create false coordination. Shutdown is not request-safe — RPC replies fire-and-forget. (P1) Session close reports success even when Excel teardown fails, masking real failure. Operation tracking is wired but dead in production. (P2) Diagnostics weak, graceful/force-stop separation needed. **Decision:** Pause PR #651. Initiate P0 daemon hardening (startup readiness + shutdown request-safety). Require deterministic focused tests, not retry-tuning or flaky smoke scripts. Real fix requires redesign at daemon orchestration layer.
- 2026-04-01: **CHART HARDENING MCP/CLI PARITY ASSESSMENT.** MCP/CLI parity verified — no gap exists in current implementation. Both use identical `ChartCreateResult` and `ChartInfoResult` structure, collision detection wired in both. Cost of enrichment (result classes, MCP schema, generator, test rebaseline) outweighs marginal value. Recommendation: Defer indefinitely; if deferred decision is lifted, implement minimal shape only — add single optional `CollisionWarning: bool` + `SuggestedNextAction: string`. No enum types or complex restructuring. Generator-based updates maintain automatic parity.

- 2026-04-06: **Error diagnostics first slice.** The safest first milestone is additive transport enrichment only: keep `ServiceResponse` as the shared contract, add optional `ExceptionType`/`HResult`/`InnerError`, and mirror them into both MCP and CLI envelopes while also emitting both `error` and `errorMessage` for compatibility. Focused issue #585-style transparency coverage is stable when run surgically per scenario; full MCP class runs can still be flaky because `ProgramTransport` session tests occasionally lose the created session between setup and first tool call, so validate individual regression slices until that harness instability is addressed separately.
- 2026-04-02: **Team closeout for the first diagnostics slice.** McCauley's parity gate landed as an additive transport contract: shared `ServiceResponse` diagnostics now flow through both MCP and CLI, both keep `error` + `errorMessage` plus `isError`, and focused #585 buckets are the trustworthy gate while broader `ProgramTransport` session flakes are treated separately.
- 2026-04-26: When an older MCP-only bug report like #585 resurfaces, rerun the focused MCP and CLI parity buckets before changing code. If `RangeFormatIssue585RegressionTests` and `RangeFormatIssue585CliParityTests` both pass on current HEAD, treat the bug as already fixed on the branch and require a fresh current-build repro before reopening implementation.
- 2026-04-26: A repo-wide "latest versions" sweep still has to stop at the newest secure, releasable version. `@vscode/vsce` 3.9.1 still reopens the `@azure/identity -> @azure/msal-node -> uuid` audit chain, so `2.25.0` remains the correct packaging version until upstream fixes it, and Spectre.Console.Cli `0.55.x` requires CLI command overrides to be `protected` plus any direct command tests to invoke them indirectly.

## Session Log

### 2026-04-26: Documentation PR and Inbox Consolidation
- Executed scoped documentation PR (#616) with strict scope control (README.md, docs/INSTALLATION.md, gh-pages/index.md only)
- Pre-commit validated all 14 gates passed (COM leaks, coverage, success flag, CLI/MCP smoke tests, packaging, MCPB bundle, skills deliverables, dynamic casts)
- Dependency review passed; merged via squash to main at commit 34e766e
- Scribe consolidated 21 inbox decision files into decisions.md (deduplicated, chronological ordering)
- Created orchestration log entry and session log for PR #616 completion
- Team updated: Cheritto history appended with session summary
- 2026-04-26: Nullable enum parameters in MCP tool signatures make the MCP SDK publish null enum members in JSON schema, which downstream strict clients can surface as invalid empty enum values. The stable fix is generator-side: keep only the primary action as a required enum, emit other action-specific enum inputs as optional strings, and parse them locally (or leave them as raw strings for [FromString] paths) so MCP and CLI stay aligned.
- 2026-04-26: **Dependency upgrade implementation phase completed.** Spawned as background agent to execute dependency manifest upgrades (global.json, central packages, VS Code extension deps/lockfile) with intentional version hold decisions for repo-specific breakage. Upgraded: global.json .NET versions, VS Code extension package.json TS/vscode engine/build tools, llm-tests Python deps via uv lock. **Intentionally held:** Microsoft.ApplicationInsights* at 2.23.0 (3.0.0 breaking change requires Azure Functions migration, out of scope), @vscode/vsce at ^2.25.0 (downstream uuid advisory in 3.x, 2.25.0 stable and verified clean on npm audit + npm run package). All changes staged locally with decision justification for team review. Outcome: dependency manifests upgraded with documented holds and readiness state for test execution phase.

## Daemon Rescue Session Finalization (2026-05-13T09:13:35Z)

Session: Inbox consolidation, orchestration logging, agent history sync
Status: ✅ APPROVED — All gates passed

- Decisions.md consolidated (9 inbox entries merged, 1 archived)
- Team orchestration logs created
- Session ready for production deployment
- Residual risk (prompts) accepted and documented
