Decision Log

Point-in-time records of specific decisions — context, alternatives, and reasoning as they stood when each call was made. For current policy and principles, see Design Principles.

Doc	Date	Status	Summary
Project Fork	2026-05-09	decided	Fork from xing5/mcp-google-sheets; alternatives evaluated
Composite Tools	2026-05-22	decided	Case analysis of specific composite tools approved or ruled out
Testing Approach	2026-05-13	decided	Why AI-directed manual verification over automated integration tests
Publishing Strategy	2026-05-23	draft	Two-track PyPI release (stable + edge); version injection open
Docs Formatting Architecture	2026-06-17	decided	Two-layer approach (direct API tools + HTML abstraction via AST); phase plan for #41, #65–#70, #79–#82
Chart Theming and Phase 3 Integration	2026-06-17	decided	No parsing layer for charts; no Vega-Lite adoption; unified brand config (docs + charts sections) for Phase 3 theme system
Grid Data Size Cap	2026-07-03	decided	Post-fetch response-size check (not pre-fetch cell-count estimate) for get_sheet_data(include_grid_data=True); configurable cap + local_path bypass; empirically falsified two earlier approaches
Cache Invalidation	2026-07-07	decided	set_cache_ttl tool for runtime TTL; modifiedTime-based validation for sheet/doc caches only (not folders/calendar); opt-out via CACHE_VALIDATE_MODIFIED_TIME
Dev-Team Roles	2026-07-11	decided	Named Orchestrator/Dev/QA ×2-lane team, persistent worktree slots, one combined MCP config for Agent View, branch-prefix lane routing
Async Tool Execution	2026-07-12	decided	Full tool layer converted to async def + asyncio.to_thread(); asyncio.gather() for 6 multi-call tools; per-thread HTTP transport fix for the newly-introduced shared-service concurrency risk; cache.py stays synchronous by design
Release QA Lead and Tech Writer Roles	2026-07-12	decided	Aziz/Amy persistent slots, no dedicated MCP server, Aziz borrows Sky/Kit via Agent-tool subagents for sharded live release QA, Amy claims documentation-labeled issues
Repositioning	2026-07-14	decided	Source-verified comparison vs. official Google Workspace MCP (dev preview, no Sheets/Docs coverage at all) and community alternatives; informational framing, not a superiority claim; narrows the Docs "deepest" claim, surfaces gaps to roadmap.md Tier 4
sync_folder Recursion	2026-07-15	decided	recursive param walks matching subfolders to any depth; asymmetric subfolders only created/entered on the side direction permits, else reported under folders_skipped; fixed a pre-existing folder-as-Workspace-file bug found during the same-logic extraction
Prompt QA Role	2026-07-21	decided	Bob (Senior Prompt Engineer) persistent slot; team-process self-edits now require prompt-qa-approved PR review before Kai merges (mechanical fixes exempt); retires the 2026-07-18 direct-push-to-develop grant that let an unreviewed permission grant harden into a standing exception
Auth-Status Limitation Categories	2026-08-02	decided	server://auth-status's _SA_LIMITED_TOOLS generalized to _SA_LIMITATIONS, a per-failure-class list (reason/alternatives no longer shared across unrelated restrictions); adds transfer_ownership's no-personal-Drive-identity class alongside the existing no-storage-quota class; ADC's own identity ambiguity scoped out to #506
Response-Size Cap Re-Evaluation	2026-08-07	decided	Live-tested up to 2MB: the client-connection-death failure mode the cap defends against no longer reproduces on the current primary MCP client; raised MAX_TOOL_RESPONSE_CHARS default 40000 → 1000000, kept the hard-error mechanism as defense-in-depth for other/untested clients; cross-client guidance scoped out to #555
Pillow Image Dependency	2026-08-07	decided	Added Pillow (not hand-rolled header parsing) as a core dependency for inline-image dimension checks + opt-in auto-downscale (#400); validation/downscale scoped to sources whose bytes are already local or in Drive, not bare http(s):// URIs
mcp v2 Resource Context Access	2026-08-20	decided	mcp.server.fastmcp → mcp.server.mcpserver (#175) was a search-and-replace everywhere except two resources: get_context() has no v2 replacement for a static resource, so server://auth-status reads a new process-wide auth.get_lifespan_context() singleton instead; the template resource spreadsheet://{id}/info uses v2's native ctx: Context injection, which tools already relied on unchanged
Local-Filesystem Test Harness	2026-08-22	decided	Opt-in tests/integration/ pytest package spawns the real server over stdio for the ~27 ⚠️ local-filesystem QA cases decision-testing.md's human-led flow structurally can't reach; self-skips with no credentials/CI impact; 3 representative tests, not all 27; CI wiring left as a separate open decision
Comments as a First-Class, Cross-Suite Capability	2026-08-28	decided	Generalizes the existing Docs-flavored comment tools to tools/drive/comments.py under generic names (breaking rename, no domain-duplicated wrappers — Google's own drive scope doesn't split comments by product either); full comments/replies CRUD parity target; cell notes get their own module; cell-anchored Sheets comments confirmed infeasible via three live experiments, closed outright
Condition-Type Docstring Generation	2026-09-15	decided	_CONDITION_SPECS single source of truth for add_data_validation's per-condition-type value count + docstring prose (#751); docstring generated at import time via explicit __doc__ assignment before manual tool() application, since a computed value can't populate __doc__ as a literal and decoration happens synchronously with def
supportsAllDrives Lint Check	2026-09-22	decided	AST-based pre-commit check (scripts/check_supports_all_drives.py) over a runtime service wrapper for the recurring supportsAllDrives=True omission foot-gun (#696/#687); method set confirmed live against the Drive v3 discovery doc, not assumed
Gmail Domain	2026-09-21	decided	First Gmail domain ship (#785): 11 primitives (read / send-draft / organize) on gmail_service + three Gmail scopes; OAuth-only for now; Calendar wiring as template; composites (find-unanswered, send-reminders) and permanent delete explicitly out of scope
Converted-Doc Change Detection	2026-09-26	decided	convert_markdown Docs stop using Drive's modifiedTime for change detection (#814): it lags Docs edits by minutes and its late update overwrites the post-create restamp. Local changes are compared against a source mtime stamped in properties, Drive edits through revisions.list against a recorded import revision; both-sides-changed becomes a conflict instead of a silent overwrite. Follow-up (#860): sync_folder(resolve=...) clears such a conflict per name, keep_drive or keep_local, keeping the file ID
Review-Finding Ticket Bar	2026-10-04	decided	Review findings default to send-back; a ticket needs a named bar in a required finding list (qa.md step 3), checked by Kai at merge (merge-pr.md step 2); bar 2 restated as "outside this PR's diff"; from-review label for measurement
Tool Error Visibility Under mcp 2.3	2026-10-04	decided	mcp 2.3 withholds any non-ToolError exception text; _timed re-raises an allowlist (auth, HttpError, GoogleAuthError, network, ValueError, OSError) as ToolError and leaves real crashes masked; same for spreadsheet://{id}/info via ResourceError; mcp>=2.3.0,<3 with the lock bumped so CI matches PyPI installs (#872)
Role-File History	2026-10-08	record	Incident history behind the rules in dev.md, qa.md, aziz.md, kai.md, and bob.md, moved there verbatim by #849 so each role file keeps only its rules
Impact × Reach Triage	2026-10-13	decided	One impact × reach rubric places every defect/hygiene ticket in a version, on every triage path (replaces #995's from-review-only rule); hygiene never gets its own release label; a follow-up chain stops gating the release after its second follow-up; QA and Dev answer four seam questions each pass (#1024)