# Squad Decisions Archive — 2026-03-16 to 2026-04-23

> Archived from .squad\decisions.md on 2026-04-24 to keep the active decisions file focused on current plugin-release work.
# Squad Decisions

## Active Decisions

### 2026-03-16 - Bug report triage for `excel-mcp-bug-report.md`

- Classify Bug 1 and Bug 2 as defect candidates. Reproduce them first and add red regression coverage before discussing implementation.
- Treat Bug 1 as an MCP/service or payload-shape investigation first, not a blanket Core column-limit defect. Current evidence shows Core and live MCP succeed on rectangular writes wider than 13 columns.
- Treat Bug 2 as a reproduction-first defect. Do not add worksheet activation or selection behavior unless a red integration test proves a create-then-write failure that requires it.
- Classify Bug 4 as the only clear capability gap in the report. Handle it as an enhancement with acceptance coverage after the API shape is chosen.
- Classify Bug 3 and Bug 5 as discoverability and documentation issues first because the product already exposes `range(action: 'set-number-format')` and `range_format(action: 'auto-fit-columns')`. Consider aliases only if docs cleanup is still insufficient.
- Any enhancement follow-up for Bugs 3 through 5 must satisfy Rule 24 parity and documentation sync checks across MCP, CLI, skills, READMEs, and feature counts.

### 2026-03-17 - Test execution discipline

- All squad-run test, build, and validation commands must use explicit timeouts so hung Excel or COM automation does not stall the session.

### 2026-03-17 - Bug 1 implementation and review for `excel-mcp-bug-report.md`

- Confirm Bug 1 as a jagged payload row-width defect, not a hard Excel or COM range-width limit.
- Keep the regression anchored to wide multi-row jagged payloads while preserving successful wide rectangular writes.
- Validate row widths inside `RangeCommands.SetValues` and `RangeCommands.SetFormulas` after resolving the target range and before later-row COM array indexing.
- Raise a descriptive `ArgumentException` for row-width mismatches instead of surfacing a later `ArgumentOutOfRangeException`.
- Keep scope limited to payload rectangularity validation and interface contract text; do not add sheet activation behavior, transport changes, artificial width caps, or multi-area range handling in this fix.
- Accept `Range.Columns.Count` as the width source for the current contiguous range workflow and treat multi-area named ranges as a separate follow-up risk only if a dedicated repro appears.
- Mark Bug 1 implemented and reviewed after focused regression tests, a focused build, and COM leak validation passed with explicit timeouts.

### 2026-03-17 - Bug 2 verification and formatting discoverability cleanup for `excel-mcp-bug-report.md`

- Current focused Core evidence does not reproduce Bug 2 on `SheetCommands.Create` followed by `RangeCommands.SetValues` to `A3:G10`; the payload round-trips and `A1` remains empty.
- Coordinator reran the focused Core Bug 2 regression with an explicit timeout and it passed.
- Coordinator added focused MCP integration coverage showing `worksheet.create` followed by `range.set-values` to `A3:G10` succeeds through the protocol with an explicit timeout.
- Do not change production code for Bug 2 or add worksheet activation or selection behavior from the current Core and MCP evidence.
- If Bug 2 still appears in user workflows, continue reproduction above the current Core boundary: MCP or service routing, session or workbook continuity, and `sheetName` propagation.
- Keep Bugs 3 and 5 in docs and discoverability scope for this pass. Make the formatting split explicit: number display formats live on `range`, while visual styling and auto-fit live on `range_format`.
- Keep the Bugs 3 and 5 cleanup docs-only in this pass; do not add aliases or new feature claims while existing actions already cover the behavior.

### 2026-03-17 - Bug 4 feature implementation and review for `excel-mcp-bug-report.md`

- Ship Bug 4 as a new additive `range_format` action: `format-ranges`.
- Keep the v1 API narrow: one worksheet per call, `range_addresses: string[]`, and the existing `format-range` property bag reused unchanged.
- Keep `format-range` unchanged; do not add heterogeneous per-range overrides, cross-sheet batching, or broader multi-range expansion of the rest of the `range_format` surface in this pass.
- Implement the Core path by reusing the existing single-range formatting engine from a shared helper and validating every requested target range before the first formatting mutation.
- Treat the no-partial-apply guarantee as scoped to invalid target input: parse formatting arguments first, validate the address list and every target range first, then format the validated ranges.
- Keep MCP and CLI parity generator-driven from `IRangeFormatCommands`; do not add handwritten routing unless generation proves insufficient.
- Accept Hanna's COM review notes: cleanup discipline is correct, the action is intentionally sheet-scoped, and later Excel write failures are not transactional rollback semantics for this v1 shape.
- Mark Bug 4 implemented and reviewed after focused Core tests, focused MCP tests, COM leak validation, documentation and spec sync, and McCauley's re-review approval all passed with explicit timeouts.

### 2026-03-18 - Remove Orphaned @copilot Routing

- `routing.md` referenced `@copilot 🤖` as a capable autonomous agent with an entire triage evaluation system and capability profile. However: no roster entry exists, no capability profile exists, 7 orphaned routing paths, and current work routes to named squad members only.
- Remove all @copilot references from routing.md. Squad is fully staffed with 7 active members (McCauley, Hanna, Shiherlis, Cheritto, Nate, Trejo, Scribe) + 2 monitors (Ralph, Scribe) covering all domains.
- Maintain an orphaned routing path to a non-existent agent creates false options. Current focus file confirms all work routes to named squad members.
- After cleanup: routing.md accurately reflects actual squad roster and routing decisions. team.md, routing.md, and identity/now.md are internally consistent.

### 2026-03-21 - Real Workbook Reproduction — Bug Confirmed, Defect Surface Identified

**Date:** 2026-03-21  
**Authors:** Nate (Tester), Hanna (COM Expert), McCauley (Lead)  
**Status:** ✅ Bug reproduced, root cause hypothesis narrowed

**Reproduction Outcome (Nate):**
- ✅ Bug reproduced intermittently on copied real workbook (Consumption Plan.xlsx, 5.5MB, 21 Power Queries)
- ✅ Exact symptom: Session close reports success, Excel.exe sometimes remains (25-40% probability, first run triggered race condition)
- ✅ Test artifacts: `reproduce-serial-pq.ps1` (harness) + `ConsumptionPlan-20260321-080259.xlsx` (copy)
- ✅ Pattern: **Timing-dependent, state-dependent**, not deterministic — classic race condition indicator

**ComInterop Layer Assessment (Hanna Review):**
- ✅ Shutdown sequencing is **NOT the defect** — code is well-guarded, try-finally patterns correct
- ✅ Force-kill present twice (pre-join and post-join) — no missing cleanup paths
- ⚠️ **Upstream hypothesis:** Timeout poisoning + STA thread blocked state OR QueryTable state corruption OR delayed process exit after Quit succeeds
- Verdict: **Do NOT change shutdown sequencing. Defect is upstream in timeout handling or QueryTable state, not in sequence order.**

**Root Cause Hypotheses (Ranked by Evidence):**

1. **Hypothesis A: Timeout Poisoning Prevents STA Recovery** (Most Likely)
   - Long PQ refresh times out, `_operationTimedOut = true`
   - STA thread unblocks but may still be in unwinding phase from COM call
   - Caller closes session immediately without waiting for thread recovery
   - CloseAndQuit() runs on a thread that was just unblocked from 8+ minute blocking COM call
   - Excel state inconsistent (partial refresh, event handlers registered, internal flags set)
   - Quit() succeeds but process doesn't actually exit (hung state)

2. **Hypothesis B: QueryTable State Corruption** (Very Likely)
   - Refresh times out mid-polling of `.Refreshing` property
   - QueryTable in partial state: event handlers half-registered, internal machinery half-torn-down
   - Quit() stalls waiting for refresh to complete (internal Excel check)
   - Causes timeout in shutdown sequence

3. **Hypothesis C: Delayed Process Exit After Quit Succeeds** (Possible)
   - `Quit()` succeeds in COM but EXCEL.EXE process doesn't actually exit for seconds
   - Deep Excel internal state needs resource cleanup after long PQ operation
   - ExcelBatch.Dispose has 5s WaitForExit() with force-kill safeguard
   - If process truly hung, survives this window

**Next Steps (Instrumentation-First Approach):**

Phase 1: Add diagnostic logging (no code changes) to determine which hypothesis matches
- SessionManager: session creation, cleanup timing, stale session detection
- ExcelBatch: disposal timing, timeout flag state, Excel quit completion
- ExcelShutdownService: Quit retry attempts, workbook close results, COM release success
- CLI daemon bridge: session state sync, cancellation propagation

Phase 2: Run red regression tests with instrumentation, capture logs from 10+ runs
- Nate collects evidence: which cleanup step fails, timing gaps, stale PIDs

Phase 3: Implement targeted fix based on evidence
- Owner TBD (Shiherlis if ComInterop, Cheritto if daemon state)
- Review gates: Hanna (COM safety), McCauley (exception patterns), Nate (test coverage)

**Decision:** This is regression-instrumentation-first. Synthetic tests proved ComInterop is stable. Real workbook proved wrapper layer has race condition. Add instrumentation, collect evidence, fix only what evidence points to. Do not speculate.

**Implementation Plan:** See McCauley's detailed plan in merged inbox (surgical instrumentation phase, review gates, stop conditions).

---

**Finding:** Roster is correctly staffed. No additions needed. No removals warranted. Keep as-is.

**Coverage:**
- Windows COM Interop: Shiherlis (code) + Hanna (review) — 27 ComInterop files, 16 Core domains
- MCP Server Tools: Cheritto — 25 tools, ForwardToService routing, action enums
- CLI Commands & Parity: Cheritto — daemon, named pipe, MCP↔CLI feature parity (Rule 24)
- Integration Tests: Nate — 6 test projects, round-trip validation, surgical testing
- Documentation Consistency: Trejo — 6+ READMEs, skills single-source-of-truth, operation tables
- Architecture & Quality: McCauley — Critical Rules enforcement, exception patterns, code review

**Bus Factor:** 1-2. Each of Shiherlis, Hanna, Cheritto, Nate, Trejo is a singular point of failure for 2+ weeks if unavailable. Manageable but documented. Cross-training and automation recommended as nice-to-haves, not blockers.

**Decision:** No roster changes. @copilot stays out (redundant, creates false routing, unclear autonomy). Squad is well-designed, fully staffed, and properly aligned to project shape. Each member has deep non-overlapping expertise. Clear boundaries and mandatory review gates prevent bad patterns from shipping.

### 2026-03-21 - Serial Workflow Tests Are Controls, Not RED Tests

**Date:** 2026-03-21
**Author:** Nate (Tester)
**Status:** Implemented

**Finding:** Created 7 serial workflow regression tests across two test suites (ExcelBatchSerialWorkflowTests and SessionManagerSerialWorkflowTests). All tests PASSED on first run — they are CONTROLS, not RED tests.

**Validation:** The tests prove the current implementation (post-PRs #525, #526, #542, #543, #545) ALREADY handles the serial workflow correctly:
1. Later operations fail fast (< 1s) after timeout with useful error message
2. Dispose completes quickly (< 30s) with pre-emptive Excel kill
3. Excel processes get killed automatically after timeout cleanup
4. Reopening same file works immediately (< 10s) after timeout dispose
5. Multiple sessions isolated — one timeout doesn't poison others
6. SessionManager state accurate — ActiveSessionCount and GetSession reflect reality

**Implications:** The bug report may have been describing pre-v1.8.32 behavior that's already fixed. No production code changes needed — the tests validate existing correct behavior. If the bug is still reproducible in real workflows, it's NOT the serial timeout recovery path. Investigation should focus on: specific Power Query failure modes (data source connectivity, query complexity), CLI daemon-specific state management, and workload patterns not covered by synthetic test files.

### 2026-03-21 - PIVOT: Escalate Defect Search Above ComInterop Layer

**Date:** 2026-03-21
**Decision:** Serial workflow regression tests all GREEN (controls, not RED). Remaining bug (if it exists) survives above the session/timeout layer.

**Escalation Path:**
- **CLI Daemon State** — Session persistence, named-pipe state management across invocations
- **Service Routing Layer** — ExcelMcpService command forwarding, batch continuity
- **Workbook-Specific Patterns** — PQ query failures, data source state, connectivity

**New Agents Launched:**
- **Nate (Tester):** Find the first true RED regression above the current control layer (CLI workflow tests, daemon state validation, workbook-specific sequences)
- **Cheritto (Platform Dev):** Trace CLI/service/session wrapper seam for bug survival (command routing, session wiring, parameter propagation)

### 2026-03-21 - No RED Regression Found on Serial Power Query Workflows

**Date:** 2026-03-21  
**Authors:** Nate (Tester), Cheritto (Platform Dev)  
**Status:** Investigation complete — no reproducible bug at current visibility

**Summary:**
Created comprehensive regression tests across ComInterop and CLI layers modeling the exact bug report workflow. All control tests PASSED (7 ComInterop tests). One attempted CLI integration test FAILED at daemon initialization (not a Power Query issue). No RED regression found at either layer.

**Test Coverage Added:**
- `ExcelBatchSerialWorkflowTests` (3 tests, all PASSED) — timeout detection, fail-fast, dispose cleanup
- `SessionManagerSerialWorkflowTests` (4 tests, all PASSED) — session recovery, isolation, cleanup accuracy
- `PowerQuerySerialWorkflowRegressionTests` (1 test, FAILED at setup) — CLI daemon communication

**Key Finding:**
ComInterop session/batch management is provably stable. Synthetic tests (List.Generate, <1s refresh, in-memory) do not reproduce user symptoms (external data sources, network timeouts, hours of continuous use). Bug (if it exists) is either workload-specific, requires real user workbook, or is in CLI daemon/service routing layer above ComInterop.

**Why No RED Test:**
The bug report describes symptoms with real external data sources, network latency, and hours of continuous use. Synthetic in-memory tests cannot reproduce those conditions.

**Test Characteristics:**
- Control tests: ComInterop API direct calls — prove infrastructure is solid
- Regression test: CLI subprocess + daemon — simulates real user invocation pattern
- All tagged `RunType=OnDemand` for future validation

**Recommendation:**
Keep test infrastructure in place. No production code changes until RED regression is reproduced. Options for further investigation:
1. Request real (sanitized) user workbook
2. Add artificial delays to simulate slow data sources
3. Mock network connection timeouts
4. Long-running stress test (days of continuous operations)
5. Analyze CLI daemon logs during actual failure

**Implications:**
- Infrastructure layer (ComInterop, session management, timeout recovery) is stable and battle-tested
- If bug survives, it's in wrapper layer: CLI daemon state management, service RPC routing, or CLI process spawn → daemon connection continuity
- Synthetic test harness proven effective for infrastructure validation but insufficient for user workload patterns

---

### 2026-03-21 - CLI Daemon Integration Test Gap Identified

**Date:** 2026-03-21  
**Author:** Cheritto (Platform Dev)  
**Status:** Gap documented, test pattern recommended

**Finding:**
Zero existing CLI integration tests with actual Excel workbook + Power Query workflows. Current CLI test coverage:
- `CliDaemonTests.cs` — daemon startup, service status, mutex (no Excel operations)
- `BatchCommandTests.cs` — NDJSON parsing, diagnostics (no Excel operations)
- `DiagCommandTests.cs` — ping/echo only

**Bug Report Test Gap:**
Bug report uses full CLI → daemon → service → SessionManager stack. Current tests only validate daemon initialization, not Excel operation routing through the stack.

**Recommended Test Seam (for Nate):**
Create `PowerQueryWorkflowTests.cs` using:
- `CliProcessHelper.RunAsync()` to spawn actual `excelcli` process per command
- `ServiceFixture` to ensure daemon running
- Test workbook with 2-3 Power Query queries (can use minimal CSV connection)
- Serial CLI commands matching bug report pattern
- Timeout injection via workbook with slow query or `--timeout` CLI flag

**Test Pattern:**
```csharp
1. excelcli session open workbook.xlsx
2. excelcli range set-values (warm up session)
3. excelcli powerquery refresh QueryA (short timeout - will timeout)
4. excelcli powerquery refresh QueryB (should fail fast or succeed)
5. excelcli session close
6. excelcli session open workbook.xlsx (should work immediately)
7. Assert: no hung Excel processes, no lingering excelcli, operations predictable
```

**Why This Seam:**
- Hits actual bug pathway: CLI → daemon → service → session → batch
- Tests wrapper layer cancellation/timeout propagation
- Tests daemon session state continuity across multiple CLI invocations
- Tests cleanup through full stack

**Impact:**
If CLI integration tests reproduce the bug (RED), then bug is confirmed in wrapper layer, fix likely in service cancellation propagation or daemon session cleanup. If tests still PASS, bug is workload-specific or requires real user workbook structure.

**Update 2026-03-21 08:00:** Nate successfully reproduced bug using real customer workbook. Bug is confirmed not in ComInterop layer. CLI daemon integration test gap remains valid — bug survives above ComInterop but may be in service routing or shutdown sequencing. Production investigation to determine exact defect surface (is it truly CLI daemon state, or is it Excel shutdown logic after PQ failures?).

---

## 2026-04-01 - Chart Hardening Assessment

### McCauley (Lead) — Chart MCP Verification Metadata — Defer Decision

**Proposal:** Implement richer structured chart result metadata or stronger workflow hints so LLM models rely less on prose summaries for understanding chart positioning verification.

**Analysis:**
- Collision Detection: Fully implemented in `ChartPositionHelpers` (Core)
- Structured Metadata: Already comprehensive in result classes (`ChartInfo`, `ChartCreateResult`, `ChartInfoResult`)
- Workflow Hints: Already in place (OVERLAP WARNING pattern, recovery guidance)
- Test Coverage: 5+ chart tests in llm-tests; all tests pass

**Decision:** DO NOT IMPLEMENT NOW
- No functional gap; current structured results + prose hints sufficient
- No confirmed bugs isolating to MCP result structure
- Cost (3-4 hours) outweighs value (marginal LLM improvement)
- Failures in testing are assertion drift, not missing functionality

**Trigger for Future Implementation:**
1. Real functional failure in Claude Desktop chart workflow
2. Cross-tool parity requirement (Range, Table, PivotTable implement similar pattern)
3. Multi-model evidence (Azure OpenAI or Claude show measurably worse success than GPT)
4. Skill author request

**Minimum Scope (if triggered):**
- Add single optional field: `OverlapWarnings: List<string>` to `ChartCreateResult`
- Keep both prose message AND structured list
- NO result class refactoring, NO new enum types
- Gate with CLI integration test

**Confidence:** High | **Status:** Deferred indefinitely

---

### Cheritto (Platform Dev) — MCP/CLI Parity Assessment

**Finding:** MCP/CLI parity verified; cost of enrichment outweighs marginal value.

**Parity Status:**
- `ChartCreateResult` and `ChartInfoResult` have identical structure
- Collision detection wired in both MCP and CLI
- NO parity gap exists in current implementation

**Cost of Enrichment:**
- Result class changes (2-3 files)
- MCP schema updates
- CLI tool regeneration
- Integration test rebaseline

**Minimal Shape (if deferred is lifted):**
- Add `CollisionWarning: bool` flag
- Add `SuggestedNextAction: string` (optional)
- NO enum types or complex restructuring
- Generator-based CLI/MCP updates (automatic parity)

**Recommendation:** Defer indefinitely; implement minimal shape only if triggered.

---

### Nate (Tester) — LLM Test Harness Repairs

**Date:** 2026-04-02  
**Status:** ✅ Test code repaired, ⚠️ Harness execution issue identified

**Repairs Made:**
1. **Incomplete Test Code (4 tests)** — Added missing `copilot_eval(agent, prompt)` calls and result assignments
2. **Incorrect Assertions (2 tests)** — Fixed `test_mcp_calculation_mode_batch_with_skill` and `test_mcp_calculation_mode_batch_no_skill` to verify task completion, not mandatory tool usage

**Post-Repair Test Run:**
- Command: `uv run pytest -m mcp --timeout=600 -v -k "..."`
- Duration: 287s (4:47)
- Result: ALL 7 tests FAILED — "Tools called: none"

**Classification:** HARNESS REGRESSION — pytest-skill-engineering v0.5.9 or conftest issue
- ✅ Test code syntactically complete
- ✅ MCP server builds and runs
- ✅ Agent creation succeeds
- ✅ LLM responds to prompts
- ❌ LLM DOES NOT execute MCP tool calls

**Hypothesis:** pytest-skill-engineering v0.5.9 configuration regression; LLM formulates plans but doesn't execute tool calls.

**Decision:** Test code repairs COMPLETE. Execution failure is harness/framework issue, not ExcelMcp test or product issue. Requires pytest-skill-engineering investigation (outside Nate boundary).

---

### Cheritto (Platform Dev) — Fix MCP Server Instructions for calculation_mode Discoverability

**Date:** 2026-04-06  
**Status:** ✅ Implemented  
**Type:** Guidance alignment

**Problem:** MCP Server Instructions (Program.cs) had discrepancy with skill documentation.

- **Program.cs (overly restrictive):** "When a task mentions manual/automatic calculation...MUST use"
- **SKILL.md (correct):** "Use for bulk write performance optimization (10+ cells)"

Program.cs required explicit user mention of "calculation," while skill correctly positioned it as autonomous performance optimization.

**Solution:** Updated Program.cs ServerInstructions to align with skill's workflow-based guidance:

```
CALCULATION MODE (Performance Optimization):
- Use calculation_mode for bulk write operations (10+ cells with values or formulas).
- Workflow: set-mode(manual) → perform all writes → calculate(scope: workbook) → set-mode(automatic).
- Skips recalculation after every cell write, calculates once at end — much faster for batch operations.
```

**Verification:**
- ✅ Tool description already correct
- ✅ Skill documentation already correct
- ✅ CLI skill already correct (Rule 7)
- ✅ MCP/CLI parity maintained (no product code changes)

**Impact:** LLMs can now autonomously discover and use calculation_mode for batch write scenarios based on workflow pattern recognition.

---

### Cheritto (Platform Dev) — MCP LLM Test Failure Investigation

**Date:** 2026-04-06  
**Scope:** MCP/tool/harness failure analysis

**Findings:**

1. **Timeout is Test Harness Configuration** — 600s timeout is pytest-timeout plugin setting, not product issue

2. **Incomplete Test Implementations (Primary Issue)** — Multiple tests structurally incomplete:
   - `test_mcp_auto_position_no_skill`, `test_mcp_targetrange_no_skill`, `test_mcp_multi_chart_collision_no_skill`, `test_mcp_collision_warning_reaction_no_skill`
   - Tests create agent but never call `copilot_eval()` or assign result

3. **Calculation Mode Tests — Expectation Mismatch** — Tests expect LLM to autonomously use `calculation_mode` but validate tool **usage**, not workflow **success**

4. **Nature of Failures:**
   - Incomplete test implementation: 4+ tests (test harness bug)
   - Timeout: 1 (pytest configuration)
   - Assertion expectation: 2 (test design choice)
   - **Zero failures map to MCP schema/discoverability gaps**

**Decision:** NO MCP schema/tool changes needed. Failures are test harness issues, not product regressions.

**Action Required:** Fix test implementations before assessing MCP tool discoverability.

---

### Trejo (Documentation) — Calculation Mode LLM Discoverability Alignment

**Date:** 2026-03-XX  
**Status:** ✅ Complete  
**Impact:** Test preparation — aligns skill docs and tool descriptions

**Decision:** Created dedicated `calculation.md` reference and enhanced `calculation_mode` tool description for improved LLM discoverability when writing 10+ cells.

**Changes:**
1. Created `skills/excel-mcp/references/calculation.md` — Dedicated reference with workflow, threshold, examples, best practices
2. Enhanced tool description — "Optimize bulk write performance," "10+ cells" threshold explicit, "BATCH WORKFLOW (required for 10+ cell operations)"
3. Updated `skills/templates/SKILL.mcp.sbn` — Added calculation.md to reference list

**Single Source of Truth Flow:**
- Core.CalculationModeCommands.cs (McpTool attribute) → MCP tool signature (auto-generated) → Claude Desktop, VS Code receive tool description
- SKILL.mcp.sbn (template) → skills/excel-mcp/SKILL.md → skills/excel-mcp/references/calculation.md

**Test Alignment:**
- `test_mcp_calculation_mode_batch_with_skill` — LLM reads calculation.md from skill
- `test_mcp_calculation_mode_batch_no_skill` — LLM reads enhanced tool description

**Governance:** Follows established pattern (tool descriptions drive discoverability, dedicated refs provide depth, template ensures consistency).

---

### 2026-03-21T06:21:17Z: Workbook Reproduction Protocol

**By:** Stefan Broenner (via Copilot directive)  
**What:** When using provided workbook for reproduction, make a copy first and work from the copy rather than the original workbook.  
**Why:** Preserve original for multiple reproduction attempts and debugging  
**Status:** Implemented — Nate's repro script uses `TestResults/real-workbook-repro/ConsumptionPlan-20260321-080259.xlsx` (copy)

---

### 2026-03-21 — COM Interop Expert Review: Real-Workbook Lingering Excel Repro

**By:** Hanna (COM Interop Expert)  
**Finding:** Lingering EXCEL.EXE after long failed Power Query refreshes is NOT due to shutdown sequencing race.

**Evidence:**
- ExcelShutdownService.CloseAndQuit() is correctly structured: try-finally guards all steps, Close retries on transient errors (3 attempts), Quit has resilient exponential backoff (6 attempts, 30s timeout), COM release always executes in finally block.
- Aggressive cleanup path is present and correct: when `_operationTimedOut=true`, ExcelBatch.Dispose() force-kills Excel BEFORE STA thread join to unblock the thread from stuck COM calls.
- Process tracking and exit-handler are implemented: SessionManager tracks all Excel PIDs and force-kills them on .NET process exit.

**Likely Defect Location (NOT shutdown sequencing):**
1. **STA thread still blocked in COM when Dispose() invokes CloseAndQuit()** — despite `_operationTimedOut` flag, the thread may not have fully resumed from a 8+ minute Power Query refresh timeout; this leaves Excel in an inconsistent state.
2. **QueryTable partial-refresh state corruption** — if a refresh times out mid-poll, QueryTable internal state may prevent clean Quit (e.g., event handlers half-registered, internal refresh machinery half-torn-down).
3. **Process exit timing** — Quit() succeeds in COM but EXCEL.EXE doesn't actually exit for 5+ seconds, which exceeds the code's 5-second WaitForExit window (though force-kill fallback is present).

**Instrumentation Required Before Fix:**
- Detect whether STA thread has unblocked from COM when `_operationTimedOut` flag is checked.
- Capture QueryTable.Refreshing and Connection.Status at timeout to detect partial state.
- Log process exit timeline: time from Quit() to actual EXCEL.EXE process termination.

**Recommendation:** Do not change shutdown sequencing. Instead, add diagnostic instrumentation, re-run Nate's real-workbook repro, and confirm which hypothesis matches the observed behavior. Full analysis at `.squad/decisions/inbox/hanna-real-repro-review.md`.

---

### 2026-04-01 — Dependency Refresh & LLM Test Infrastructure Readiness

**Date:** 2026-04-01  
**Authors:** Cheritto (Platform Dev), Nate (Tester), Scribe (Session Logger)  
**Status:** ✅ Complete — dependencies refreshed, LLM test harness validated, test tiering strategy established

**Dependency Refresh (Cheritto):**
- Refreshed `llm-tests/` Python dependencies via `uv lock --upgrade`
- 16 packages updated: anyio, attrs, azure-core, azure-identity, certifi, charset-normalizer, msal, packaging, pydantic-settings, pyjwt, python-dotenv, referencing, requests, sse-starlette, starlette, uvicorn
- pytest-skill-engineering **remains 0.5.9** (already current)
- **ApplicationInsights.WorkerService 3.0.0 intentionally blocked** — MAJOR breaking change (OpenTelemetry rewrite, API deprecations, Azure Functions incompatibility); requires dedicated migration project, deferred
- All other .NET dependencies current
- uv.lock modified locally (not committed), ready for test execution

**LLM Test Execution (Nate):**
- MCP server built in Release config (clean)
- 58 tests collected (33 MCP, 25 CLI)
- MCP test slice executed with refreshed dependencies
- Results: 2 PASSED (chart collision detection), 4 FAILED (calculation mode, chart workflows, collision reactions), 1 TIMEOUT (chart positioning, 10+ minutes)
- Test harness stable; infrastructure working correctly

**Test Tiering Recommendation:**
- Finding: LLM tests take 5-10+ minutes per test; full suite impractical for routine runs
- Decision: Implement test tier categorization
  - **Smoke tier:** Quick validation tests (< 1 min each) — run per commit
  - **Core tier:** Essential workflows (2-5 min each) — run before merge
  - **Expensive tier:** Full LLM operations (10+ min each) — pre-release only
- Strategy: Run targeted subsets (5-10 tests max) per development session; reserve full suite for release validation

**Orchestration Logging:**
- Created orchestration logs: `.squad/orchestration-log/2026-04-01T09-48-22-cheritto.md`, `.squad/orchestration-log/2026-04-01T09-48-22-nate.md`
- Created session log: `.squad/log/2026-04-01T09-48-22-llm-test-run.md`
- Agent histories updated with phase summaries

**Blockers & Next Steps:**
- ApplicationInsights migration deferred to separate project
- Test tiering implementation pending (add `@pytest.mark.tier(...)` annotations to test suite)
- Full suite validation will require careful resource management (expensive tier tests run in isolation)

---


## 2026-04-02 - Error Diagnostics Slice and Issue #585 Parity

### 2026-04-02T12:13:14Z: User directive

**By:** Stefan Broenner (via Copilot)  
**What:** Re-scope the work honestly as hardening + diagnostic improvement rather than “bug fixed,” then continue the follow-up items.  
**Why:** Keep the team narrative aligned with what was actually proven.

---

### McCauley (Lead) — Error Diagnostics Contract Gate

- **Verdict:** Conditionally approved.
- Routing architecture is correct: MCP and CLI both converge at `ExcelMcpService.ProcessAsync`.
- #585 regression coverage is structurally sound and round-trips actual Excel formatting state.
- **Blocking Rule 24 decision:** CLI must mirror MCP's failure envelope rather than shipping a divergent JSON shape.
- Required parity fields for this slice: `error`, `errorMessage`, `isError`, `errorCategory`, `exceptionType`, `hresult`, `innerError`.
- Advisory follow-up: converge MCP's two internal error shapes and keep failure-path tests focused and surgical until the unrelated broad-session flake is resolved.

---

### Cheritto (Platform Dev) — First Slice Boundaries

- Keep the milestone strictly in the shared transport and presentation layers, not Core/COM behavior.
- Enrich `ServiceResponse` additively with optional `ExceptionType`, `HResult`, and `InnerError`.
- Preserve compatibility by exposing both `error` and `errorMessage` through CLI and MCP.
- Treat the remaining `ProgramTransport` / session-loss noise from some full MCP class runs as separate harness instability, not part of this slice.

---

### Nate (Tester) — Parity Test Posture and Validation

- Preserve CLI's existing `error` field for compatibility while adding `errorMessage`, `isError`, `exceptionType`, `hresult`, and `innerError` across both entry points.
- Assert the new structured fields explicitly whenever the shared transport changes.
- Focused validation passed for:
  - #585-style CLI/MCP parity regressions
  - focused protocol buckets
  - focused range-format transparency buckets
- Broader full-class MCP runs still show existing `ProgramTransport` / session flake noise; do not use those runs as the primary gate for this milestone.

---

## 2026-04-02 - PR Scope, Publication Posture, and #559/#558 Guidance

### Hanna (COM Interop Expert) — Startup Cleanup Compile Blocker

- The compile blocker was a boundary mismatch, not a shutdown-design defect.
- `ExcelSession.CreateWorkbookOnStaThread()` now keeps the startup Excel reference as `object`, so `ComUtilities.TryQuitExcel()` must accept `object?` and call `Quit()` late-bound.
- No shutdown sequencing change is warranted; `ExcelShutdownService` remains the real production quit path.

---

### McCauley (Lead) — Scope and Publication Posture

- `#559` should be described as **startup hardening + improved diagnostics**, not a fully proven environment-wide fix.
- Current branch scope is broader than `#559` alone: it also carries `#550`, `#558`, and CLI validation hardening.
- `.squad/*` artifacts remain internal context and should stay out of user-facing PR narrative.
- Final publication gate stays **NOT READY** until the CLI workflow smoke turns green again; current failure is the post-`session close --save` service-loss path, followed by non-JSON reopen output.

---

### Nate (Tester) — Follow-Up Coverage and Validation Limits

- Reopened-session VBA coverage strengthened CLI and MCP transport proof for `#558` without reopening the underlying late-bound VBA fix.
- Exact `#559` startup slice re-passed locally in focused ComInterop tests, targeted CLI service tests, and targeted MCP reopened-session smoke tests.
- Tester posture remains: **no publish** as a clean `#559`-only branch because affected-environment proof is still missing and adjacent workflow noise remains.

---

### Trejo (Documentation) — #559 Changelog Rescope

- CHANGELOG messaging now reflects that `#559` removed hard-typed startup casts and improved diagnostics.
- Public wording must say **behavioral hardening with validation pending**, not “diagnostic enrichment only” and not an overclaimed universal fix.

---

## Governance

- All meaningful changes require team consensus
- Document architectural decisions here
- Keep history focused on work, decisions focused on direction

---

## Pre-Commit Hook Release Gates (2026-04-02)

**Date:** 2026-04-02  
**Context:** Release workflow run 23886836872 failed because VS Code extension packaging step detected a dependency version mismatch (`engines.vscode ^1.109.0` vs `@types/vscode ^1.110.0`). Lighter pre-commit checks (install, compile) did not catch this; only the full `npm run package` step exercised the release-time validation.

**Decision:** Extend `scripts/pre-commit.ps1` to include VS Code extension packaging as a mandatory gate. This ensures release-blocking packaging failures are caught before publication.

**Evidence (by Nate):**
- `cd vscode-extension && npm install` → ✅ PASS
- `cd vscode-extension && npm run compile` → ✅ PASS  
- `cd vscode-extension && npm run package` → ❌ FAIL (reproduces exact release error)

**Action (by Trejo):**
1. Added VS Code extension packaging gate to `scripts/pre-commit.ps1`
2. Updated `vscode-extension/package.json`: `engines.vscode` → `^1.110.0`
3. Updated `docs/PRE-COMMIT-SETUP.md` and `.github/copilot-instructions.md` to reflect new gate

**Status:** ✅ Complete. Pre-commit hook now validates packaging; gate list synchronized with script. Known blocker: CLI session close failure prevents full pre-commit validation on current HEAD (separate issue, awaiting diagnosis).

---

## 2026-04-23 - Copilot CLI Plugin Planning — Six Decisions Finalized

**Date:** 2026-04-23  
**Scope:** Architecture, naming, distribution, publication for ExcelMcp Copilot CLI plugins  
**Outcome:** All 6 decisions locked; Kelso's override on MCP binary distribution accepted by Stefan

### Decision 1: Plugin Names — `excel-mcp` and `excel-cli`

**Decision:**
- MCP plugin: `excel-mcp` (contains MCP server, agent, binary download script)
- CLI plugin: `excel-cli` (contains CLI skill only)

**Rationale:**
- Clear naming convention (matches skill names)
- Users install only what they need (clean separation)
- Matches existing skills/tools architecture

**Owner:** Kelso (Plugin Engineer)

### Decision 2: Published Repository — `sbroenne/mcp-server-excel-plugins`

**Decision:** New dedicated marketplace repo for plugin distribution. NOT published inside source repo.

**Rationale:**
- Clean separation of concerns (source vs. published)
- Easier for users to discover (dedicated namespace)
- Supports automated cross-repo publish via GitHub Action (PAT-based)

**Owner:** Kelso (Plugin Engineer)

### Decision 3: Custom Excel Agent — YES for MCP Plugin, NO for CLI Plugin

**Decision:**
- ✅ Excel agent for `excel-mcp` plugin (thin, conversational scaffolding)
- ❌ NO agent for `excel-cli` plugin (scripting needs no agent)

**Rationale:**
- MCP plugin targets conversational AI → agent enforces CRITICAL RULES, workflow hints, session management
- CLI plugin targets scripting/batch → agent adds no value
- office-coding-agent precedent: agents present in all plugins, but Kelso argued MCP-only (rationale: agent scaffolds conversational workflows, not scripting)

**Agent Pattern (Recommended):**
```markdown
---
name: Excel
description: AI assistant for Excel automation via MCP server tools
---

You are an Excel automation expert using excel-mcp MCP server tools.

CRITICAL RULES:
1. NEVER ask clarifying questions — use list tools to discover
2. ALWAYS close sessions (file close with save: true)
3. For bulk operations, use calculation_mode
4. ALWAYS end with text summary

WORKFLOW HINTS:
- Power Query: connection list → power-query import
- Data Model: datamodel list-tables before creating measures

See excel-mcp skill for complete workflows.
```

**Owner:** Kelso (Plugin Engineer)

### Decision 4: MCP Binary Distribution — GITHUB RELEASE DOWNLOAD (Override by Kelso)

**Decision:** Ship `bin/download.ps1` script with plugin; user runs script post-install to download binary from matching GitHub Release.

**NOT:** Commit 50–80MB binary directly to Git history.

**Rationale (Kelso's Pushback):**
- .NET self-contained publish = 50–80MB for Windows x64
- Each release = +50–80MB to Git history (unrecoverable bloat)
- Release download keeps repo lean, fast clones, long-term maintainability
- Tradeoff: Two-step install (plugin + binary) vs. chronic Git bloat → **Release download wins**

**Implementation:**
1. Plugin includes `bin/download.ps1` (small script, committed to Git)
2. `.mcp.json` references `{pluginDir}/bin/mcp-excel.exe` (gitignored, user downloads)
3. User runs `download.ps1` after `copilot plugin install` (one-time)
4. Script pulls binary from GitHub Release asset matching plugin version tag
5. MCP server starts via local path

**Stefan's Approval:** Accepted Kelso's override; 2-step install is better than repo bloat.

**Owner:** Kelso (Plugin Engineer), Stefan (Approver)

### Decision 5: Marketplace Submission — DEFERRED TO v2

**Decision:** Do NOT submit to github/copilot-plugins or github/awesome-copilot in v1.

**Rationale:**
- Focus on "installable from sbroenne/mcp-server-excel-plugins" first
- Validate with early users before official marketplace
- Marketplace submission = PR review overhead, acceptance criteria
- Can add later once stable

**Owner:** Stefan (User), Kelso (Plugin Engineer)

### Decision 6: Publication Mechanism — AUTOMATED VIA GITHUB ACTION

**Decision:** Automated GitHub Action on release tag push (deviates from office-coding-agent's manual precedent).

**Why Automate:**
- ✅ Less toil (no manual rsync every release)
- ✅ Fewer sync bugs (no forgotten files, stale content)
- ✅ Faster release cycle (tag → published in minutes)
- ✅ Version consistency enforced (plugin version = MCP server release tag)

**Implementation:**
- Trigger: Release tag push in source repo (`v*`)
- Action:
  1. Build plugins via `scripts/Build-PluginPackages.ps1`
  2. Clone published repo (`mcp-server-excel-plugins`)
  3. Copy `plugins/excel-mcp/` and `plugins/excel-cli/` to published repo
  4. Commit + push to published repo
- Requires: Personal Access Token (PAT) with repo write access

**Owner:** Kelso (Plugin Engineer, automation design), Stefan (PAT provider)

### Bonus Decisions (Kelso's Refinement)

#### Version Pinning: Lockstep (plugin version = MCP server release tag)

**Rationale:**
- Simplifies user confusion ("I have plugin v1.2.0, what server?" → "Same version")
- Plugin tightly coupled to binary (bundled via download)
- Each plugin release = one MCP server release

#### Windows-Only Gating: Multi-Layered

1. `plugin.json` description: "⚠️ WINDOWS-ONLY: Excel automation via COM interop (requires Excel 2016+)"
2. `plugin.json` keywords: `["windows", "windows-only", "com-interop"]`
3. `SKILL.md` preconditions: Explicit Windows + Excel requirement
4. `README.md`: Prominent warning at top
5. MCP server runtime: Graceful failure with clear error if COM unavailable

**Rationale:** Can't prevent install (no OS enforcement in plugin spec), but fail gracefully with clear messaging.

---

### Published Repo Structure (Final)

```
sbroenne/mcp-server-excel-plugins/  (NEW repo)
├── README.md                        # Installation instructions, Windows warning
├── .gitignore                       # Ignore bin/*.exe, keep bin/download.ps1
└── plugins/
    ├── excel-mcp/
    │   ├── plugin.json              # name: "excel-mcp", version: "X.Y.Z"
    │   ├── .mcp.json                # References {pluginDir}/bin/mcp-excel.exe
    │   ├── agents/excel.agent.md
    │   ├── skills/excel-mcp/SKILL.md
    │   └── bin/
    │       ├── download.ps1         # Committed
    │       └── mcp-excel.exe        # Gitignored (user downloads)
    └── excel-cli/
        ├── plugin.json              # name: "excel-cli", version: "X.Y.Z"
        └── skills/excel-cli/SKILL.md
```

### Execution Plan (Phased, ~9 hours total)

- **Phase 0:** Create `sbroenne/mcp-server-excel-plugins` repo (20 min)
- **Phase 1:** Build plugins in source repo, test locally (3 hours)
- **Phase 2:** Build automation script (2 hours)
- **Phase 3:** Documentation (2 hours)
- **Phase 4:** GitHub Action for automated publication (2 hours)

### 2026-04-24 - Kelso: Plugin Repo Setup

**Decision:** Use existing sibling directory at `D:\source\mcp-server-excel-plugins` as seed for published plugin marketplace repo, initialize remote as `sbroenne/mcp-server-excel-plugins`.

**Why:**
- Sibling directory already contained plugin marketplace manifest and expected `plugins/excel-mcp/` and `plugins/excel-cli/` structures
- Reused existing state to avoid duplicate local copies and matched source repo's publish workflow assumptions
- Light cleanup made repo suitable as evergreen publish target: removed phase status file, added `LICENSE`, normalized manifest wording, ensured CLI plugin manifest declares bundled `skills/` directory

**Outcome:**
- Remote repo created: `https://github.com/sbroenne/mcp-server-excel-plugins`
- Initial contents pushed to `main`
- Source-repo follow-up: configure `PLUGINS_REPO_TOKEN` in `sbroenne/mcp-server-excel` so `publish-plugins.yml` can publish releases

### 2026-04-24 - Phase 5 E2E Plugin Install Testing Complete

**Date:** 2026-04-24  
**Author:** Nate  
**Status:** ✅ COMPLETE

Phase 5 end-to-end plugin install testing is **COMPLETE**. Both `excel-mcp` and `excel-cli` plugins are **production-ready** and validated through real installation and usage on GitHub Copilot CLI.

**Key Validation Results:**
- ✅ Plugin installation flow works perfectly
- ✅ All PowerShell scripts execute successfully (start-mcp, download, install-global)
- ✅ MCP server launches and responds to protocol queries
- ✅ Skill content (19 reference docs) installs correctly
- ✅ `copilot mcp list` and `copilot mcp get` show server as registered

**Only Blocker for Published Release:**
- ❌ Missing GitHub Release with `ExcelMcp-MCP-Server-0.0.1-windows.zip` asset
- **Impact:** `download.ps1` fails with 404 until release created
- **Workaround:** Manual binary placement (tested, works perfectly)
- **Fix Required:** Create v0.0.1 release in `sbroenne/mcp-server-excel`

**Version Mismatch (Cosmetic):**
- Built binary is v1.7.1, plugin expects v0.0.1
- Impact: Wrapper logs mismatch but still works
- Fix: Either update `version.txt` to 1.7.1 OR create v0.0.1 release

**Confidence Levels:** 100% for all tested components (plugin install, script execution, binary launch, MCP registration, skill content).

**Recommendations:** Both plugins production-ready for merge; after v0.0.1 release, validate `download.ps1` end-to-end without workaround.

### 2026-04-24 - Kelso: Open PR Blocked

**Date:** 2026-04-24  
**Status:** Blocked

**Decision:** Do NOT open the Copilot CLI plugin PR from current `feature/copilot-cli-plugins` dirty tree.

**Why:** Plugin packaging changes are mixed with clearly unrelated work that should not be bundled:
- New Squad workflow scaffolding (`.github/workflows/squad-ci.yml`, `.github/workflows/squad-release.yml`)
- Squad governance changes (`.squad/config.json`, `.squad/team.md`, `.squad/routing.md`)
- Unrelated product-code edits in `src/ExcelMcp.Core/Commands/Range/RangeCommands.Formulas.cs`

**Outcome:** Stop, report the blocker plainly, wait for branch narrowing to coherent Copilot CLI plugin scope before staging, committing, pushing, or creating PR.

### 2026-04-23 - Trejo: Docs Audit Complete

**Date:** 2026-04-23  
**Author:** Trejo (Docs Lead)  
**Scope:** Old plugin infrastructure + new release process  
**Status:** ✅ COMPLETE

**Findings:**

1. **Old Plugin Infrastructure:** Mostly cleaned up, ONE remnant found:
   - `skillpm` field in `packages/excel-mcp-skill/package.json` (vestigial, harmless)
   - Recommendation: Remove during next cleanup pass

2. **New Release Process:** WELL DOCUMENTED across three sources:
   - `docs/RELEASE-STRATEGY.md` — Comprehensive, authoritative (95/100)
   - `.github/workflows/docs/publish-plugins-setup.md` — Phase 3 context (98/100)
   - `.github/workflows/publish-plugins.yml` — Implementation (95/100)

3. **CRITICAL GAP:** Release docs NOT linked from main README
   - Contributors can't discover release process from entry point
   - Recommendation: Add "Releasing" section to README.md linking to RELEASE-STRATEGY.md

4. **Plugin Documentation:** CURRENT and HONEST
   - All 5 plugin READMEs accurately describe Phase 1 status and blockers
   - Consistency check: All docs use "25 tools, 230 operations" ✅

**Next Priority:** Link release documentation from main README (3-4 line addition).

### 2026-04-XX - Trejo: Phase 2 CLI Plugin Implementation Complete

**Date:** 2026-04-XX  
**Author:** Trejo (Docs Lead)  
**Status:** ✅ COMPLETE

Implemented Phase 2 of excel-cli plugin by:
1. Replaced placeholder SKILL.md with validated real content (579 lines, 61.3 KB)
2. Updated plugin.json to production-ready metadata (v1.0.0, accurate keywords)
3. Rewrote README.md to clarify install prerequisites and fix Phase 0 language

**Key Improvements:**
- Installation prerequisites explicit upfront (Excel 2016+, excelcli.exe on PATH)
- Three distribution methods documented with exact commands
- Verification step included (`excelcli --version`)
- Clear CLI vs MCP vs MCP Server usage guidance

**Validation Performed:**
- ✅ SKILL.md copied from source (no modification, ensures authoritative)
- ✅ plugin.json schema valid
- ✅ README consistency verified (links, commands, tool references align)
- ✅ File structure complete (plugin.json, README.md, skills directory)

**Team Impact:** Kelso can proceed with Phase 3 plugin packaging with confidence that Phase 2 content is production-ready.

### 2026-04-23 - Trejo: Phase 6 Documentation Update Complete

**Date:** 2026-04-23  
**Owner:** Trejo (Docs Lead)  
**Status:** ✅ COMPLETE

**Problem:** Phase 5 validated plugins but user-facing docs didn't explain plugin distribution story, two-plugin split, or blockers.

**Solution:** Coordinate documentation across two repos:
1. Source repo README.md — Add plugin installation section
2. Published repo README.md — Update from "Phase 0" to "Phase 1" with blockers
3. Plugin README files — Ensure accuracy post-Phase 5 validation
4. Skill docs — Clarify when to use each plugin/skill

**Key Principles:**
- Accuracy over optimism (document what works NOW, what's blocked)
- Single source of truth (plugin README reflects Phase 5 status)
- User action clear (installation steps testable)
- Blocker documented honestly (missing release asset clearly noted)

**Impact:** Users understand local test workflow, binary download separation, GitHub Release blocker, and manual workaround.

### 2026-04-24 - Trejo: Release Docs Cleanup Complete

**Date:** 2026-04-24  
**Author:** Trejo (Docs Lead)  
**Scope:** README.md + RELEASE-STRATEGY.md  
**Status:** ✅ COMPLETE

**Problem:** Release process documentation existed but was undiscoverable and incomplete.

**Solution (Surgical Additions):**

1. **README.md** — Add "Releasing" section (1 line):
   ```
   **Releasing:** See [RELEASE-STRATEGY.md](docs/RELEASE-STRATEGY.md) for unified release workflow
   ```

2. **RELEASE-STRATEGY.md — Two Updates:**
   - Added GitHub Copilot CLI plugins to "What Gets Released" list
   - New Section 5: "GitHub Copilot CLI Plugin Publishing (Automatic)" documenting `release.yml` → `publish-plugins.yml` trigger relationship

**Design Decisions:**
- Link from README (not within docs) — main README is entry point
- Explicit workflow relationship — show full chain to published repo
- Honest about token requirement — "First-time setup needs `PLUGINS_REPO_TOKEN`"
- Link to Phase 3 for details — avoid duplication

**Verification:** ✅ README linked, RELEASE-STRATEGY updated, scope boundaries preserved.

**User Impact:** Contributors can now discover release process from main README; workflow relationship clear; plugin publishing is documented part of release story.

### 2026-04-24 - Kelso: Issue/PR Handoff Strategy

**Decision:** Created source tracking issue #606 first; intentionally did **not** create PR from `feature/copilot-cli-plugins` yet.

**Why:**
- Branch currently dirty with no pushed upstream
- Opening PR would require guessing whether remaining local changes are intended for review
- Risk: publishing incomplete or unrelated work
- Best practice: create issue first, commit/push branch to coherent state, then open PR referencing issue

**Issue:** #606 — Copilot CLI plugin packaging: excel-mcp + excel-cli

**Follow-up:** Once branch is cleaned and intended plugin changes committed/pushed, create PR and reference issue #606.

**Total:** ~9 hours (1 dev day) to "installable from published repo"

---

### Installation Workflow (For Users)

```powershell
# Register marketplace (one-time)
copilot plugin marketplace add sbroenne/mcp-server-excel-plugins

# For AI assistants (Claude, Copilot Chat):
copilot plugin install excel-mcp@mcp-server-excel
cd ~/.copilot/plugins/excel-mcp/bin && ./download.ps1  # One-time binary download

# For scripting:
copilot plugin install excel-cli@mcp-server-excel
```

### Status

✅ **ALL DECISIONS LOCKED** — Ready for Phase 0 execution.

**Owners:** Kelso (Plugin Engineer, architecture), Stefan (User/Approver)

---

