mcp-gee-sweet 0.7.0.dev87__tar.gz → 0.7.0.dev93__tar.gz

{mcp_gee_sweet-0.7.0.dev87 → mcp_gee_sweet-0.7.0.dev93}/.claude/commands/cleanup-worktrees.md

@@ -1,6 +1,6 @@
 Remove worktrees under `.claude/worktrees/` whose branch has a merged PR, so completed tickets don't pile up as stale directories. Safe by default: never deletes anything with uncommitted or unpushed changes — those are reported, not touched.
 
-1. List current worktrees: `git worktree list --porcelain`. Skip the main checkout (the entry with no `.claude/worktrees/` path).
+1. List current worktrees: `git worktree list --porcelain`. Skip the main checkout (the entry with no `.claude/worktrees/` path). Also skip the six dev-team slot worktrees (`.claude/worktrees/ash`, `sky`, `jay`, `kit`, `aziz`, `amy`) unconditionally — they're persistent, not one-off ticket worktrees, and are never removed by this command regardless of branch/PR state. `/merge-pr` resets them to idle (`team/<name>`) in place after each ticket merges; this command has no role there.
 2. For each remaining worktree, get its branch name and check whether it has a merged PR:
    ```
    gh pr list --repo khuisman/mcp-gee-sweet --state merged --head <branch> --json number,url,mergedAt

{mcp_gee_sweet-0.7.0.dev87 → mcp_gee_sweet-0.7.0.dev93}/.claude/commands/merge-pr.md

@@ -5,9 +5,11 @@ Merge the current branch's PR and clean up its worktree. Uses `--admin` only to
    - `state` must be `OPEN`.
    - Every check in `statusCheckRollup` (in particular "Lint and test") must show success. If anything is failing or still pending, stop and report which — do not merge, and do not wait/poll.
    - `mergeable` must not be `CONFLICTING`.
+   - If the branch's second `/`-separated segment is one of the four dev-lane slot names (`ash`, `sky`, `jay`, `kit` — the type prefix in front varies, `feat`/`fix`/`chore`/etc., don't assume `feat`), it must carry the `qa-approved` label (check `gh pr view <number> --json labels`). If it doesn't, stop — that means the paired QA agent (`/team-member`) hasn't signed off yet; don't merge and don't review it yourself here. This check deliberately stays scoped to the four dev-lane names — Aziz's and Amy's branches (`team/aziz`, `docs/amy/issue-<n>`, ...) aren't part of the Dev/QA pairing and go through normal review instead.
 3. Show the user a summary: PR number, title, URL, check status, and review status (expected to be blocked only on the missing-approval requirement). State plainly that merging will use `--admin` to bypass that review gate. Ask for explicit confirmation before proceeding.
 4. On confirmation, squash-merge (matching this repo's existing history — commits land on `develop` as a single `title (#number)` commit): `gh pr merge <number> --admin --squash`. The remote branch is auto-deleted on merge (repo setting), so don't pass `--delete-branch`.
 5. Clean up:
+   - If the merged branch's second segment was one of the six dev-team slot names (`ash`, `sky`, `jay`, `kit`, `aziz`, `amy`) — again, regardless of its type prefix — **do not remove the worktree**: it's a persistent slot, not a one-off. From that worktree, reset it to idle instead: `git fetch origin develop`, `git checkout team/<name>`, `git reset --hard origin/develop`, then delete the just-merged branch by its actual name (`git branch --show-current` before switching, or read it off the PR's `headRefName` — don't assume it starts with `feat/`). Report that the slot is back to idle, ready for its next ticket.
    - If the current branch is a `review/<headRefName>` branch created by `/verify-pr` (not a `.claude/worktrees/*` worktree — just a local branch in the main checkout), there's no worktree to remove: switch to `develop` and `git branch -D review/<headRefName>`.
    - If this session created the current worktree (i.e. it got here via `/start-worktree` or `/next-issue` earlier in this same session), use `ExitWorktree` with `action: "remove"`.
    - Otherwise (worktree predates this session), fall back to manual cleanup from the main checkout: `git worktree remove <path>`, then `git branch -d <branch>`, then `git worktree prune`.

mcp_gee_sweet-0.7.0.dev93/.claude/commands/orchestrator.md

@@ -0,0 +1,21 @@
+Establish this session as **Kai**, the orchestrator — the one session responsible for ticket triage, lane assignment, roadmap grooming, live testing, and merging PRs, as opposed to a worker session doing ticket implementation in a worktree. Code review and live QA belong to the Sky/Kit QA agents now (see `/team-member`) — Kai's merging step just checks their work landed (`qa-approved` label) rather than redoing it.
+
+Why this role split exists: any locally-configured MCP server that runs this project via `uv run --directory <path>` (check your global MCP config for one pointing at this repo), plus the `mcp-gee-sweet` docker-compose service (bind-mounts `./src`), always serve whatever is checked out at that fixed path — the main checkout, not whichever worktree a session's shell happens to be in. A worktree's code is invisible to every live MCP tool call until it's checked out in the main checkout or merged to the default branch. So only one place can ever do meaningful live testing — the main checkout — and only one session should treat it as home base at a time.
+
+1. Confirm this session is running from the main checkout, not a `.claude/worktrees/*` path. If it's in a worktree, tell the user the orchestrator role requires the main checkout and ask whether to `ExitWorktree` (`keep`) first.
+2. Check `git branch --show-current` and `git status --short` on the main checkout:
+   - On `develop` and clean: ready.
+   - On a feature branch, or dirty: flag it. Ticket implementation shouldn't live in the main checkout under this model — it blocks freely checking out other branches to live-test them. Ask the user whether to move that work into its own worktree (`start-worktree`) or continue as-is for now.
+3. Report current state so the user can steer:
+   - `git worktree list` — active worker worktrees
+   - `gh pr list --state open` — PRs awaiting live-test/review/merge (run from inside the repo so `gh` infers it from the git remote — don't hardcode a repo slug, forks won't match)
+   - `gh issue list --label ready-for-development --state open` — queued ticket(s)
+4. State the orchestrator's responsibilities plainly:
+   - Ticket triage, labeling, and **lane assignment**. If the dev-team is active (`.claude/worktrees/ash` and `.claude/worktrees/jay` exist), also check which lane is idle before labeling the next ticket: a Dev slot is idle if its worktree is on `team/<name>` rather than a ticket branch, or equivalently if no open PR's branch has `<name>` as its second `/`-separated segment (`gh pr list --state open --json headRefName --jq '[.[] | select((.headRefName | split("/"))[1] == "<name>")]'` — the type prefix in front varies, don't assume `feat`). Only label a new `ready-for-development` ticket once a lane is actually free to pick it up — Ash and Jay each work one ticket at a time. When deciding what to label next: check the active roadmap-planning memory (memory index, not a hardcoded filename) for phase order and any noted dependencies, then cross-reference `git worktree list` / `gh pr list --state open` to see which phase-fronts are already claimed. Before labeling a ticket to run *in parallel* with other in-flight work, check whether it (or the roadmap memory) flags it as cross-cutting or conflict-risk (e.g. a rewrite touching most/all tool files) — that's what the `solo-only` GitHub label means: apply it to the issue, and while it's the only thing labeled `ready-for-development`, don't add any other ticket's `ready-for-development` label alongside it, no matter how many lanes are idle. The label pairing (not lane-count discipline) is the actual control — `/next-issue` only ever sees what's labeled, so an unlabeled ticket can't be grabbed regardless of how many lanes ask. Re-label the held-back tickets `ready-for-development` once the `solo-only` one ships.
+   - Roadmap grooming (`docs/roadmap.md` + whichever roadmap-planning memory is currently active — check the memory index rather than assuming a specific version-numbered file)
+   - Live/manual tool testing — only possible here (or in a QA agent's own worktree, once it's checked out a branch — see `/team-member`)
+   - Merging PRs that carry the `qa-approved` label (`merge-pr`) — do not merge one that's missing it, and do not perform the review/QA yourself; send it back to the relevant QA agent instead
+   - Worktree cleanup after merge (`cleanup-worktrees`) — this must never remove the six dev-team slot worktrees, only ad hoc worker worktrees
+   - Release readiness and documentation quality are Aziz's and Amy's territory, not Kai's — when cutting a release, hand off to Aziz (`/team-member Aziz`) for the review/QA-tier/sign-off pass rather than doing it here; route doc gaps found along the way to Amy (`documentation` label) rather than fixing them inline.
+
+   Do NOT pick up ticket implementation directly in this session — hand it to a worker session via `start-worktree` (or `next-issue`, which does this automatically), or to a dev-team lane via `/team-member` if the team is active.

{mcp_gee_sweet-0.7.0.dev87 → mcp_gee_sweet-0.7.0.dev93}/.claude/commands/prep-for-pr.md

@@ -9,7 +9,7 @@ Review the current branch against this checklist and report the status of each i
 - [ ] **Regression coverage** — were tests that touch the modified files (not just new tests) also run?
 - [ ] **QA test cases written** — are there AI-driven test cases in `docs/qa/tests/` covering the changed behavior? This applies beyond new tools: a change to shared internal code under `src/mcp_gee_sweet/tools/` (e.g. `docs/emitter.py`, `sheets/helpers.py`) that alters what a live tool call produces needs a test case too — a unit test alone confirms the function's internal contract, not the real API output. If this is a bug fix, the test case should reproduce the regression scenario itself, not just spot-check the tool's happy path.
 
-**Live QA execution is out of scope for this checklist.** If this session is a worker in a `.claude/worktrees/*` checkout, running live QA tools here would exercise the main checkout's code, not this branch's changes — the result would look real but prove nothing. Do not run live tests and do not write `**Result**` entries from a worktree. That happens in the orchestrator's `/verify-pr` pass after the PR is open, in the main checkout, where the branch's actual code is reachable by the live MCP tools. Leave the `**Result**` line off new/changed test cases entirely — don't stub it as "pending," just omit it so `/verify-pr` adds the first real one.
+**Live QA execution is out of scope for this checklist.** If this session is a worker in a `.claude/worktrees/*` checkout, running live QA tools here would exercise the main checkout's code, not this branch's changes — the result would look real but prove nothing. Do not run live tests and do not write `**Result**` entries from a worktree. That happens after the PR is open, in a place where the branch's actual code is reachable by live MCP tools: the orchestrator's `/verify-pr` pass in the main checkout for a plain worker PR, or the paired QA agent's pass (`/team-member Sky`/`/team-member Kit`) in its own dedicated worktree for a dev-team lane PR. Leave the `**Result**` line off new/changed test cases entirely — don't stub it as "pending," just omit it so that pass adds the first real one.
 
 ## 2. QA test case tags
 

mcp_gee_sweet-0.7.0.dev93/.claude/commands/team-member.md

@@ -0,0 +1,88 @@
+Bootstrap this session as a named member of the dev team. Takes the name as an argument (e.g. `/team-member Ash`). Only ever used by an agent spawned from within the `make claude-team` session — the top-level session itself is always Kai (Orchestrator) and uses `/orchestrator` instead.
+
+## Roles
+
+| Name | Role | Lane | Worktree | Partner |
+|---|---|---|---|---|
+| Ash | Dev | A | `.claude/worktrees/ash` | Sky |
+| Sky | QA | A | `.claude/worktrees/sky` | Ash |
+| Jay | Dev | B | `.claude/worktrees/jay` | Kit |
+| Kit | QA | B | `.claude/worktrees/kit` | Jay |
+| Aziz | Release QA lead | — | `.claude/worktrees/aziz` | — |
+| Amy | Tech writer | — | `.claude/worktrees/amy` | — |
+
+Aziz and Amy aren't lane-paired — they operate at release cadence, not per-ticket, so they have no `Partner` and no dedicated MCP server (see §2).
+
+If the argument doesn't match one of these six (case-insensitively), stop and say so — `Kai` is the top-level session itself and has no `/team-member` entry.
+
+## 1. Isolate into the slot
+
+`EnterWorktree` with `path` set to that name's worktree from the table (it already exists — `make claude-team` provisions all six before launch via `scripts/setup_team.sh` — so this always re-enters, never creates). If `EnterWorktree` reports the path doesn't exist, stop and tell the user to run `make claude-team` first.
+
+## 2. State the tool boundary
+
+Every role's MCP servers are connected in this session because `scripts/setup_team.sh` copies `.claude/mcp-configs/team.mcp.json` to a `.mcp.json` in the repo root and in each worktree — Claude Code auto-discovers a project-level `.mcp.json` per working directory. (Agent-view sessions do **not** inherit the `--mcp-config`/`--strict-mcp-config` CLI flags passed to whatever process launched `make claude-team` — confirmed live 2026-07-11, a spawned session's `/mcp` showed only the user's global `~/.claude.json` servers until the per-worktree `.mcp.json` was added. If a role's `/mcp` is ever missing the team servers, re-run `scripts/setup_team.sh` and have that session run `/mcp` again — restarting the session may be required to pick up a newly-added project `.mcp.json`.) Say plainly: this session must only call tools prefixed `mcp__mcp-gee-sweet-<name>__` (lowercase name) — and `mcp__playwright__` if QA, respecting the filesystem-mutex protocol in `docs/qa/run.md` §"Coordinating Playwright across parallel shards" since the other QA lane may be using it too. Never call another role's `mcp__mcp-gee-sweet-<other>__` tools even though they're visible in this session's tool list.
+
+**Aziz and Amy are the exception to "own prefix only."** Neither gets a dedicated `mcp-gee-sweet-aziz`/`mcp-gee-sweet-amy` server — `scripts/setup_team.sh` still copies them the full `.mcp.json`, so every server is visible in their tool list, but they have no server of their own to call directly. Amy generally shouldn't need one (docs work is filesystem-only). Aziz's whole job requires calling other roles' tools during a release QA pass — see §5 for when that's allowed and how it stays safe (borrowing only while the dev team is idle, delegating the actual calls to subagents rather than driving them directly).
+
+## 3. Dev role (Ash / Jay)
+
+Check the current branch in this worktree (`git branch --show-current`):
+
+Branch naming for this slot always puts `<name>` as the **second** `/`-separated segment — `<type>/<name>/issue-<n>` — where `<type>` is whatever this repo's existing convention calls for given the ticket's nature (`feat`, `fix`, `chore`, `docs`, ...; see recent branch names for precedent). It is *not* always `feat` — don't assume that prefix anywhere, including when matching branches below; match on segment position, not a literal `feat/` string.
+
+- **On `team/<name>` (idle):** this slot is free. Get the queue: `gh issue list --repo khuisman/mcp-gee-sweet --label ready-for-development --state open --json number,title,body,labels --jq 'sort_by([(.labels | map(.name | select(startswith("v"))) | sort | first // "v9.9"), .number])'`. Filter out any issue number already claimed by an *open* PR anywhere in the repo (so Ash and Jay never grab the same ticket): `gh pr list --state open --json headRefName --jq '[.[].headRefName]'` and drop any issue whose number appears in one of those branch names. Take the lowest-numbered remaining issue, confirm it with the user, then:
+  1. Pick `<type>` to match the ticket (feature vs. fix vs. chore/docs), then `git fetch origin develop && git checkout -b <type>/<name>/issue-<n> origin/develop`.
+  2. Work through the issue fully — code, tests, doc changes.
+  3. Run the test suite.
+  4. Run `/prep-for-pr`.
+  5. Commit and push (with confirmation, per this repo's normal rule), open a PR referencing the issue (`Closes #<n>`) targeting `develop`.
+  6. Remove the `ready-for-development` label once the PR is open.
+  7. Report the PR URL. Leave the branch checked out — don't return to `team/<name>` until the ticket is fully merged (see `/merge-pr`'s team-slot reset step).
+- **On any other branch (mid-ticket):** report status — whether a PR is already open, what CI/QA said if anything, and whether it's waiting on QA or on further work — rather than claiming a new ticket.
+
+## 4. QA role (Sky / Kit)
+
+Find the partner Dev's open PR by matching the branch's second `/`-separated segment against the partner's lowercase name — not a `feat/`-specific prefix, since the Dev's branch type varies: `gh pr list --state open --json number,headRefName,url --jq '[.[] | select((.headRefName | split("/"))[1] == "<partner>")]'`. At most one is expected, since a lane only has one ticket in flight at a time.
+
+- **None found:** report that Lane {A/B} has nothing to verify right now.
+- **One found:** this is now essentially `/verify-pr`'s steps 4 onward, but simpler — this worktree already IS a dedicated review space, so skip `/verify-pr`'s steps 1–3 (the main-checkout precondition and the `review/<branch>` fetch trick don't apply here):
+  1. `git fetch origin <headRefName> && git reset --hard origin/<headRefName>` in this worktree, staying on `team/<name>` (never create a branch named after the PR here — this slot's identity is `team/<name>`, permanently).
+  2. Tell the user to run `/mcp reconnect` (standalone, on its own line) so this agent's own MCP connection picks up the reset code. Wait for confirmation.
+  3. Run `/code-review` at `high` effort against `origin/develop...HEAD`.
+  4. Scope and run the live QA steps from `/verify-pr` (its steps 6–8: find touched `docs/qa/tests/` cases, cross-check tool coverage, run them live using this worktree's own `mcp-gee-sweet-<name>`-prefixed tools).
+  5. Record `**Result**` entries for every case actually run.
+  6. If anything failed: push the recorded results (`git push origin HEAD:<headRefName>`, with confirmation), comment on the PR summarizing what failed, and stop — tell the user it goes back to the Dev agent.
+  7. If everything passed: push the results, then `gh pr edit <number> --add-label qa-approved`, and report to the user that it's ready for Kai to run `/merge-pr`.
+
+## 5. Release QA Lead (Aziz)
+
+Aziz doesn't work a ticket queue — he runs at release cadence: review everything going into a release, decide how much live testing it needs, run that testing, and sign off.
+
+**Precondition — the dev team must be idle.** Aziz borrows Sky's and Kit's worktrees and MCP tool prefixes to execute live QA (see below), so Ash/Sky/Jay/Kit must not be mid-ticket when a release pass starts. Check both lanes: `gh pr list --state open --json headRefName --jq '[.[].headRefName]'` — if any branch's second `/`-segment is `ash`, `sky`, `jay`, or `kit`, that lane is active. Also check `git -C .claude/worktrees/ash branch --show-current` and the same for `jay` — either off `team/<name>` means mid-ticket even before a PR exists. If anything is active, stop and tell the user which lane, rather than borrowing a worktree out from under live Dev/QA work.
+
+1. **Review the release.** Enumerate everything since the last stable tag: `git log v<last-stable>..origin/develop --oneline` and the merged PRs (`gh pr list --state merged --search "merged:>=<last-stable-date>"`). For each: confirm the ticket's acceptance criteria were actually met, skim the diff for anything that reads unfinished, and check whether touched features have matching doc updates (README, `docs/qa/tests/*.md` coverage for new tools, CHANGELOG if this repo keeps one).
+2. **Decide the QA tier.** Follow the scoped-gating process in `docs/qa/runs/README.md` §"Scoped gating" exactly — enumerate commits, classify behavior-change vs. pure-refactor, map to domains, decide structural vs. non-structural per domain. Default to Full Regression; only substitute Smoke + targeted Domain runs if the audit is clean. Document the audit itself in the eventual `docs/qa/runs/vX.Y.Z.md` — this is Aziz's call to make, not something to defer to the user.
+3. **Prep the borrowed worktrees.** In `.claude/worktrees/sky` and `.claude/worktrees/kit`: `git fetch origin develop && git reset --hard origin/develop` (they may be stale from the last PR either verified). Tell the user to have each of those sessions run `/mcp reconnect` if they're live, or note that a fresh `mcp-gee-sweet-sky`/`mcp-gee-sweet-kit` connection will pick up the reset code on next call.
+4. **Shard and spawn.** Split the required suites across `Agent`-tool subagents (not Agent-View spawns — those don't inherit this session's already-connected MCP servers; true subagents do), one per domain, following the v0.8.1 precedent of parallel domain-sharded execution. Each subagent's prompt must specify: which `docs/qa/tests/<domain>.md` file and which TCs, which slot prefix to call tools through (`mcp-gee-sweet-sky` or `mcp-gee-sweet-kit` — split so no two subagents share a prefix concurrently), the fixture scope it owns if sharing live data with another shard, and — critically — that it must **not** edit any tracked file itself. A subagent's job is to run the live calls and report back a structured PASS/FAIL/SKIP list with what it actually observed; only Aziz writes to the repo, so results from worktrees on two different branches never need reconciling as competing diffs.
+5. **Playwright shards** follow the existing mutex protocol in `docs/qa/run.md` §"Coordinating Playwright across parallel shards" (mkdir-based lock at `/tmp/mcp-gee-sweet-playwright.lock`, backoff-retry, ~120s staleness) — tell subagents that use `mcp__playwright__*` tools to respect it since Sky's and Kit's shards may both need it.
+6. **No fabricated results.** Only record a `**Result**` for a case a subagent actually ran and reported observing; anything blocked gets `**Result** pending — <reason>`, never a guessed outcome.
+7. **Repeat live verification** for any subagent-reported bug or fix-recheck that involves ordering, batching, or inheritance semantics rather than pure deterministic logic — one green pass isn't sufficient evidence for that class of behavior; have the subagent (or a follow-up one) repeat the cycle 2-3 times varying conditions before trusting it.
+8. **Compile.** Once all shards report back, Aziz — working in his own worktree (`.claude/worktrees/aziz`), never Sky's or Kit's — writes the inline `**Result (date) ✅/❌**` entries into `docs/qa/tests/*.md`, the aggregate `docs/qa/results/<date>.md`, and the release sign-off `docs/qa/runs/vX.Y.Z.md` (including the scoped-gating audit from step 2). Any failures found get filed as issues or routed back to the responsible Dev lane; don't sign off a release with an open failure.
+9. **Sign off.** Once every required suite is checked off and documentation review (step 1) is clean, commit the QA docs, push, open a PR, and report to the user that the release is ready to tag.
+
+For a **minor/dev release** that only needs Smoke: same flow, but step 2's audit will usually conclude Smoke alone suffices — Aziz still runs it live and records real results, just against a smaller case set.
+
+## 6. Tech Writer (Amy)
+
+Amy keeps documentation accurate, friendly, comprehensive, and fun — README, `docs/`, tool docstrings surfaced to users, and QA test docs' clarity (not their results).
+
+- **On `team/amy` (idle):** claim work the same way Ash/Jay do, but from the `documentation` label instead of `ready-for-development`: `gh issue list --repo khuisman/mcp-gee-sweet --label documentation --state open --json number,title,body --jq 'sort_by(.number)'`. Filter out issues already claimed by an open PR the same way Dev roles do. If the queue is empty, that's fine — ask the user whether there's a specific doc gap to work from instead (e.g. a just-merged feature whose docs lag behind, spotted during Aziz's release review).
+  1. `git fetch origin develop && git checkout -b docs/amy/issue-<n> origin/develop`.
+  2. Do the writing: fix inaccuracies, tighten voice, fill gaps, add examples. Read the actual code/tool behavior rather than trusting an existing doc's claims — a doc bug is exactly the kind of drift Amy exists to catch.
+  3. If a change touches user-facing tool behavior described in `docs/qa/tests/`, flag it for Aziz rather than editing test *results* herself — Amy owns doc accuracy, not QA sign-off.
+  4. Run `/prep-for-pr`, commit and push (with confirmation), open a PR referencing the issue (`Closes #<n>`) targeting `develop`.
+  5. Remove the `documentation` label once the PR is open.
+- **On any other branch (mid-ticket):** report status rather than claiming new work.
+
+Amy has no dedicated MCP server and doesn't need QA-approved sign-off to merge (docs-only PRs aren't gated by `qa-approved`) — normal `/merge-pr` review still applies.

{mcp_gee_sweet-0.7.0.dev87 → mcp_gee_sweet-0.7.0.dev93}/.claude/commands/verify-pr.md

@@ -1,5 +1,7 @@
 Verify an open worker PR before merging: code review plus live QA testing against real Google APIs. This only works from the orchestrator session in the main checkout — see `/orchestrator` for why (live MCP tools always serve the main checkout's code, never a worktree's).
 
+**If the dev-team is active** (a PR whose branch has `ash` or `jay` as its second `/`-separated segment — the type prefix in front varies, don't assume `feat`), use `/team-member Sky` or `/team-member Kit` instead — those roles have their own dedicated worktree, so the main-checkout precondition in step 1 and the `review/<branch>` fetch trick in step 3 don't apply there; QA is steps 4 onward of this file, run directly from that worktree. This file remains the path for a plain worker PR with no dev-team lane behind it.
+
 CI (the "Lint and test" check `/merge-pr` already gates on) covers unit tests. It cannot cover code review judgment or live calls against real Google APIs, since those need credentials and fixtures CI doesn't have. That's what this skill does instead — it's the step between a worker's PR going up and `/merge-pr`.
 
 1. **Preconditions.** Confirm this session is in the main checkout, not a worktree (same check as `/orchestrator` step 1). If the main checkout has uncommitted changes, stop and ask the user how to proceed — don't stash or discard anything.
@@ -42,6 +44,6 @@ CI (the "Lint and test" check `/merge-pr` already gates on) covers unit tests. I
    ```
    Ask before pushing, per this repo's normal commit/push confirmation rule. Leave the scratch worktree in place afterward (`ExitWorktree` with `action: "keep"`) for next time — don't remove it between PRs, only if the user asks for a cleanup pass.
 
-10. **Report.** Summarize: code review findings (if any), which test cases passed/failed/pending, any coverage gaps found in step 6, and whether the branch looks ready to merge. If everything passed, say the next step is `/merge-pr`. If something failed, say the PR needs to go back to its worker session — don't attempt the fix yourself here; this session's job is verification, not implementation.
+10. **Report.** Summarize: code review findings (if any), which test cases passed/failed/pending, any coverage gaps found in step 6, and whether the branch looks ready to merge. If everything passed, apply the sign-off label (`gh pr edit <number> --add-label qa-approved`) and say the next step is `/merge-pr`. If something failed, say the PR needs to go back to its worker session — don't attempt the fix yourself here; this session's job is verification, not implementation.
 
 Leave the branch checked out either way — `/merge-pr` operates on the current branch's PR, and if it needs rework, the worker's own worktree still has the branch open there too.

{mcp_gee_sweet-0.7.0.dev87 → mcp_gee_sweet-0.7.0.dev93}/.github/workflows/ci.yml

@@ -17,7 +17,7 @@ jobs:
       - uses: actions/checkout@v7
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.3.0
+        uses: astral-sh/setup-uv@v8.3.2
 
       - name: Set up Python 3.12
         run: uv python install 3.12

{mcp_gee_sweet-0.7.0.dev87 → mcp_gee_sweet-0.7.0.dev93}/.github/workflows/docs.yml

@@ -18,7 +18,7 @@ jobs:
           fetch-depth: 0  # full history so mike can see existing gh-pages versions
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.3.0
+        uses: astral-sh/setup-uv@v8.3.2
 
       - name: Set up Python 3.12
         run: uv python install 3.12

{mcp_gee_sweet-0.7.0.dev87 → mcp_gee_sweet-0.7.0.dev93}/.github/workflows/publish-dev.yml

@@ -23,7 +23,7 @@ jobs:
           fetch-depth: 0  # full history so uv-dynamic-versioning can read tags
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.3.0
+        uses: astral-sh/setup-uv@v8.3.2
 
       - name: Set up Python 3.12
         run: uv python install 3.12
@@ -45,7 +45,7 @@ jobs:
           fetch-depth: 0  # full history so uv-dynamic-versioning can read tags
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.3.0
+        uses: astral-sh/setup-uv@v8.3.2
 
       - name: Set up Python 3.12
         run: uv python install 3.12

{mcp_gee_sweet-0.7.0.dev87 → mcp_gee_sweet-0.7.0.dev93}/.github/workflows/release.yml

@@ -15,7 +15,7 @@ jobs:
       - uses: actions/checkout@v7
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.3.0
+        uses: astral-sh/setup-uv@v8.3.2
 
       - name: Set up Python 3.12
         run: uv python install 3.12
@@ -36,7 +36,7 @@ jobs:
           fetch-depth: 0
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v8.3.0
+        uses: astral-sh/setup-uv@v8.3.2
 
       - name: Set up Python 3.12
         run: uv python install 3.12

{mcp_gee_sweet-0.7.0.dev87 → mcp_gee_sweet-0.7.0.dev93}/.gitignore

@@ -22,3 +22,7 @@ site/
 # QA run artifacts
 tc-*.png
 docs/qa/results/*-partial.md
+
+# Generated, machine-specific (absolute paths)
+.claude/mcp-configs/*.json
+.mcp.json

{mcp_gee_sweet-0.7.0.dev87 → mcp_gee_sweet-0.7.0.dev93}/CLAUDE.md

@@ -70,6 +70,8 @@ Set `AUTH_METHOD` to pin a specific method with no fallback — removes ambiguit
 
 **Tool registration** (`tool` decorator wrapper): A custom `@tool()` decorator wraps `@mcp.tool()`. It checks `ENABLED_TOOLS` (set via `ENABLED_TOOLS` env var or `--include-tools` CLI arg) and skips registration for any tool not in the allowlist. This is how tool filtering works — tools simply aren't registered with FastMCP rather than being conditionally hidden.
 
+**Async execution** (`execute_in_thread` + `thread_http`, in `http_transport.py`): every `@tool()`-registered function is `async def`, and `_timed`'s wrapper is unconditionally `async def wrapper(...): return await func(...)` — so **any new tool must be `async def`**, even one with no Google API calls (see `tools/cache.py`'s `get_cache_ttl`/`set_cache_ttl`/`refresh_cache` for an example with an empty `await`-free body; a plain `def` there raises `TypeError` at call time since `await`ing a sync return value fails — `test_server.py::TestAllToolsAreAsync` guards against this recurring). Every `.execute()` call is wrapped `await execute_in_thread(chain.execute, service)` (`http_transport.py`, re-exported from `auth.py` for existing imports) — **do not** write `asyncio.to_thread(chain.execute, http=thread_http(service))` directly: `thread_http(service)` as an eagerly-evaluated kwarg resolves on the event-loop thread before the worker thread starts, so concurrent calls end up sharing one transport across threads (a real, live-reproduced bug, fixed in #183's follow-up round — see the decision doc). `execute_in_thread` defers the `thread_http()` call into the thread itself via a lambda. `thread_http()` hands each worker thread its own `AuthorizedHttp` transport built from the shared credentials, since the lifespan-scoped `sheets_service`/`drive_service`/etc. objects each carry one `httplib2` transport that isn't safe for concurrent use across threads. Six multi-call tools (`sync_folder`, `get_multiple_sheet_data`, `get_multiple_spreadsheet_summary`, `import_csv_to_sheet`, `share_spreadsheet`, `share_file`) parallelize their per-item work via `asyncio.gather(..., return_exceptions=True)` instead of looping serially. `cache.py`'s SQLite I/O deliberately stays synchronous, not `to_thread`-wrapped — see the comment in `cache.py::_open()`; the module's two Google-API-calling helpers (`get_modified_time`, `fetch_sheets`) are `async def` and do use `execute_in_thread` for their own `.execute()` calls. `_BaseCache.snapshot_epoch()`/`store(..., epoch=...)` guard against a `refresh_cache()` call landing mid-fetch and having its invalidation silently overwritten — only wired up for `SheetStructureCache`/`SheetDataCache` so far. Full rationale: `docs/decisions/decision-async-tool-execution.md`.
+
 **Two Google API clients**: The server builds both a Sheets client (`sheets/v4`) and a Drive client (`drive/v3`). Most tools use only the Sheets client; `list_spreadsheets`, `create_spreadsheet`, `share_spreadsheet`, and `list_folders` use Drive. `create_spreadsheet` uses Drive to create the file (so it can place it in a folder), not the Sheets API.
 
 **A1 notation helpers**: `_parse_a1_notation`, `_column_index_to_letter`, and `_letter_to_column_index` convert between A1 ranges and the 0-based row/column indices the Sheets batchUpdate API requires. The Sheets values API uses A1 notation directly; batchUpdate requires numeric indices — keep that distinction in mind when adding new tools.

{mcp_gee_sweet-0.7.0.dev87 → mcp_gee_sweet-0.7.0.dev93}/Makefile

@@ -68,6 +68,14 @@ docs: ## Serve docs locally at http://127.0.0.1:8000 (live reload).
 install-hooks: ## Install pre-commit hooks into the local git repo.
 	uv run pre-commit install
 
+.PHONY: setup-team
+setup-team: ## Idempotently provision/refresh dev-team worktree slots and MCP config, without launching Claude.
+	scripts/setup_team.sh
+
+.PHONY: claude-team
+claude-team: setup-team ## Launch Claude Code with all dev-team MCP servers connected (Kai/Ash/Sky/Jay/Kit/Aziz/Amy) for Agent View.
+	claude --mcp-config .claude/mcp-configs/team.mcp.json --strict-mcp-config
+
 .PHONY: test
 test: ## Run unit tests.
 	uv run python -m pytest

{mcp_gee_sweet-0.7.0.dev87 → mcp_gee_sweet-0.7.0.dev93}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-gee-sweet
-Version: 0.7.0.dev87
+Version: 0.7.0.dev93
 Summary: MCP server for Google Workspace — Sheets, Drive, Docs, and Calendar. 60+ tools for AI clients.
 Project-URL: Homepage, https://github.com/khuisman/mcp-gee-sweet
 Project-URL: Bug Tracker, https://github.com/khuisman/mcp-gee-sweet/issues

mcp_gee_sweet-0.7.0.dev93/docs/decisions/decision-async-tool-execution.md

@@ -0,0 +1,111 @@
+# Decision: Async Tool Execution (issue #183)
+
+**Date:** 2026-07-12
+**Snapshot commit:** branch `feat/ash/issue-183`
+
+## Background
+
+Every tool in this server made Google API calls synchronously and sequentially, even when a single tool logically does several independent calls — syncing N files, fetching N sheets, sharing with N recipients. FastMCP supports async tool handlers natively, so the fix is to convert the tool layer to `async def`, push each blocking `.execute()` call onto a worker thread via `asyncio.to_thread()`, and use `asyncio.gather()` to run genuinely independent calls within one tool concurrently instead of one at a time.
+
+This touches all 13 tool files (`~144` `.execute()` call sites) plus two non-`@tool` helper chains that tool functions call into: `sheets/helpers.py` (`_get_sheet_id`, `_get_sheet_index`) and `docs/emitter.py` (`fill_tables` and its recursive fill chain).
+
+## Decisions
+
+### 1. Shared-transport thread-safety fix (new scope, found during design review)
+
+Direct inspection of `mcp`'s `func_metadata.call_fn_with_arg_validation` confirmed sync tool handlers previously ran straight on the event loop thread — the server was effectively single-threaded for tool execution, so there was no existing thread-safety exposure. Converting to `to_thread`/`gather` changes that: multiple `.execute()` calls can now genuinely run in parallel OS threads against the *same* `sheets_service`/`drive_service`/etc. objects that `auth.py` builds once at startup and reuses forever. `google-api-python-client`'s default `httplib2`-backed transport is not safe for concurrent use of one instance — a new risk introduced by this change, not a pre-existing one, and in scope to fix here.
+
+**The mechanism:** `googleapiclient.http.HttpRequest.execute()` accepts an `http=` override — no need to rebuild whole service objects per thread, just swap the transport at the call site. `auth.py` gained a `thread_http(service)` helper: a `threading.local()`-cached `AuthorizedHttp` per (thread, service), built from the credentials already attached to that service's `Resource` object (`service._http.credentials`, set by `googleapiclient.discovery.build()`). Standard call sites became `await asyncio.to_thread(chain.execute, http=thread_http(service))`.
+
+`MediaIoBaseDownload.next_chunk()` doesn't accept an `http=` override (it reads `self._request.http` internally), so the three/four chunked-download sites (`export_file`, `download_file`, `download_folder`, `sync_folder`) instead set `request.http = thread_http(drive_service)` before starting the chunked loop, then wrap the whole loop in one `to_thread` call.
+
+### 2. `cache.py` (SQLite) stays fully synchronous
+
+Deliberate, not an oversight: only the actual Google API `.execute()` call inside a cache-touching helper gets `to_thread`-wrapped; the sync `cache.get()`/`cache.store()` calls stay on the single event-loop thread, interleaved between `await`s. Since only one coroutine runs on the event loop at a time (`to_thread` only offloads the specific blocking call it wraps), concurrent SQLite access never actually occurs even under `gather()` — no lock needed. A comment at the top of `cache.py`'s `_open()` spells this out so a future edit doesn't "fix" it by adding `to_thread`/locks that would actually introduce the race they're meant to prevent.
+
+### 3. `gather()` restructuring — six tools, uniform pattern
+
+Named in the issue: `sync_folder`, `get_multiple_sheet_data`, `get_multiple_spreadsheet_summary`. Extended per the issue's own "any tool that currently loops over API calls serially" scope to three more found during design review: `import_csv_to_sheet` (chunked row writes to disjoint ranges), `share_spreadsheet`, `share_file` (per-recipient/per-permission loops).
+
+**`batch_update_cells` scope correction:** the issue named it as a parallelization target, but it has no loop over API calls — it's a single already-batched `.execute()` call (the loop present is a pure Python list comprehension building the request body, no I/O). Gave it the standard async/`to_thread` conversion only; there was nothing to `gather()`.
+
+Shared pattern across all six: extract per-item work into an inner `async def`, gather with `return_exceptions=True`, reduce in one pass afterward. `return_exceptions=True` matters even though each per-item helper already catches its own errors and returns a tagged result — it also lets every in-flight item finish before an unexpected exception (a genuine bug, not the expected per-item failure path) surfaces, instead of orphaning still-running tasks. `gather()` preserves the order of the awaitables list, so `get_multiple_sheet_data`/`get_multiple_spreadsheet_summary` need no reordering. `share_spreadsheet`/`share_file`/`sync_folder` bucket results by outcome (successes/failures, uploaded/downloaded/failed) — relative order *within* a bucket now reflects completion order, not input order, since each item still carries its own identity (email, filename) in its result. `sync_folder`'s reduce pass also sums `total_bytes` and populates five separate lists from one tagged-result stream, avoiding concurrent mutation of shared accumulators entirely (only the single-threaded reduce pass after `gather()` touches them).
+
+`asyncio.to_thread`'s default executor caps at `min(32, os.cpu_count() + 4)` workers, shared process-wide — a batch larger than that queues rather than fully parallelizing. Timing stays accurate, just with diminishing returns past the cap; noted at each `gather()` site so it isn't mistaken for a bug later.
+
+### 4. Test infrastructure: `pytest-asyncio`, `asyncio_mode = "auto"`
+
+Confirmed via user decision over two alternatives (anyio pytest plugin, manual `asyncio.run()` wrapper per test). `asyncio_mode = "auto"` means converting a test is purely mechanical — `def test_x():` → `async def test_x():` plus `await` at each call site — no `@pytest.mark.asyncio` decorators needed anywhere. `MagicMock`/`Mock`-based service chains needed no changes; `asyncio.to_thread(mock_chain.execute, http=...)` runs the sync mock callable in a worker thread and awaits the result normally — the mocks don't know or care about the extra `http=` kwarg.
+
+### 5. A bug the mocked test suite structurally couldn't catch
+
+`_timed`'s wrapper (`server.py`) became unconditionally `async def ...: return await func(...)`. Any tool registered through `tool()` that was *not* itself converted to `async def` would break at call time — `await` on a plain sync return value raises `TypeError`. `tools/cache.py`'s three tools (`get_cache_ttl`, `set_cache_ttl`, `refresh_cache`) have zero `.execute()` calls, so they were correctly left out of the `.execute()`-driven conversion sweep — but that left them as plain `def` under an `async def`-only wrapper. Every existing unit test captures the raw inner function via a fake tool registry, bypassing `_timed` entirely, so `pytest -q` stayed green throughout even with this broken. Only caught by importing `server.py` directly and checking `inspect.iscoroutinefunction()` on every registered tool's unwrapped inner function — a check worth keeping in mind for any future addition of a tool with no I/O of its own. Fixed by converting all three to `async def` (trivial — no `await` needed inside, they just satisfy the wrapper's calling convention).
+
+## Verification
+
+- Full unit suite (665 tests) green; `ruff check` clean; zero unwrapped `.execute()` calls remaining (`grep -rn "\.execute()" src/mcp_gee_sweet/tools/`).
+- Manual smoke test: 5 concurrent `sync_folder` uploads (each artificially delayed 0.2s in the mock) completed in ~0.22s total, not the ~1.0s a serial implementation would take — confirms real concurrency, not just non-blocking syntax.
+- Live QA: see `docs/qa/tests/infra.md` TC-I24 and the six new per-tool cases (`docs/qa/tests/drive.md` TC-D176–179, `docs/qa/tests/sheets_read.md` TC-R36–37) — each forces enough distinct, identifiable concurrent items to catch cross-item attribution corruption under the real Drive/Sheets transport, which no mock can exercise.
+
+## Round 2 — QA findings from PR #293 review (2026-07-13)
+
+QA (`/code-review --effort high` + live testing) sent the PR back with one live-reproduced blocking bug (TC-R36) and 8 further code-review findings. All 10 are fixed here.
+
+### 6. The actual `thread_http()` bug: eager kwarg evaluation, not per-thread isolation
+
+The mechanism described in §1 was correct in intent but broken in every call site: `await asyncio.to_thread(chain.execute, http=thread_http(service))` evaluates `thread_http(service)` as a keyword argument *before* `to_thread` schedules the worker thread — Python evaluates all arguments to a call before making the call. So `thread_http()` always ran on the event-loop thread, and every concurrently-gathered call for a given service resolved the *same* cached transport, which then got used by N worker threads simultaneously — the exact hazard §1 was meant to prevent. Live-reproduced as intermittent SSL/connection errors under real concurrent load (`docs/qa/tests/sheets_read.md` TC-R36).
+
+**Fix:** `http_transport.py` (new module, extracted from `auth.py` to avoid a circular import with `cache.py` — see #9 below) gained `execute_in_thread(execute_fn, service)`:
+
+```python
+async def execute_in_thread(execute_fn: Any, service: Any) -> Any:
+    return await asyncio.to_thread(lambda: execute_fn(http=thread_http(service)))
+```
+
+`execute_fn` is the *bound but not yet called* `.execute` method (evaluating it is just attribute access — harmless on the event-loop thread); `thread_http(service)` is now called *inside* the lambda `to_thread` runs on the worker thread. All 141 standard call sites converted from `asyncio.to_thread(chain.execute, http=thread_http(service))` to `execute_in_thread(chain.execute, service)` via a verified 1:1 mechanical transform (every site's preceding line ended in `.execute,` and following line was a bare `)`, confirmed by scripted audit before transforming — no ambiguous block boundaries, unlike the regex-corruption incidents from round 1). One non-standard site (`export_revision`'s raw `.request()` call) fixed by hand with the same lambda-deferral pattern.
+
+### 7. `get_spreadsheet_info` MCP resource handler was still fully synchronous
+
+`server.py`'s `@mcp.resource("spreadsheet://{spreadsheet_id}/info")` handler predates the tool-layer conversion and was out of scope per the original plan ("tool files," not `@mcp.resource` handlers) — but that left one synchronous `.execute()` call blocking the event loop during a live API request, undermining the point of the whole conversion for that one code path. Converted to `async def`, wrapped via `execute_in_thread`.
+
+### 8. `get_modified_time()`/`fetch_sheets()` in `cache.py` issued unwrapped blocking Google API calls
+
+Both are cache-touching helpers, not `@tool()`-registered functions, so they were missed by the tool-file-scoped conversion sweep despite being called from async tool code (`sheets/data.py`, `sheets/helpers.py`, `sheets/structure.py`) — every call blocked the event loop for the duration of the underlying Drive/Sheets API request. Converted both to `async def`, wrapped their `.execute()` calls via `execute_in_thread`, and awaited all call sites. This is *not* the same decision as "`cache.py`'s SQLite I/O stays synchronous" (§2) — that's about the sync `cache.get()`/`store()` calls, which correctly stay unwrapped; this is about the actual network call these two helpers make before touching the cache at all.
+
+### 9. Extracted `thread_http`/`execute_in_thread` into `http_transport.py`
+
+Fixing #8 requires `cache.py` to call `execute_in_thread`, but `execute_in_thread` lived in `auth.py`, which already imports from `cache.py` (`SheetStructureCache` et al.) — a circular import. Moved both functions into a new `http_transport.py` with no dependency on either module; `auth.py` re-exports them (`from .http_transport import execute_in_thread, thread_http`) so none of the 13 tool files' `from ...auth import execute_in_thread, thread_http` imports needed to change.
+
+### 10. `share_spreadsheet`/`share_file` lost the identity of a malformed input entry
+
+Both tools' per-item `_share_one` closures extracted fields via `.get()` *before* entering their own try/except — a non-dict entry (e.g. a bare string in the `recipients`/`permissions` list) raised `AttributeError` from that very first `.get()` call, escaping to the outer `gather(..., return_exceptions=True)` catch-all, which only records `{"email_address": None, "error": ...}` / `{"entry": None, "error": ...}` — indistinguishable from any other anonymous failure if multiple bad entries were in the same batch. Fixed by wrapping each closure's entire body (field extraction included) in its own try/except, echoing the raw input back as `entry` even when extraction itself is what failed.
+
+### 11. `import_csv_to_sheet`'s concurrent chunk writer could leave holes mid-sheet on partial failure
+
+Before #183, a chunk-write failure stopped the (then-sequential) loop immediately, leaving a clean truncated prefix — rows 1..N present, nothing after. Under `asyncio.gather()`, chunks write concurrently, so a later chunk can succeed while an earlier one is still failing, leaving an ambiguous *hole* rather than a clean boundary, with the old code surfacing only the first raw exception and no indication of which rows were affected. Fixed: `_write_chunk` now returns a tagged `{start_row, end_row, ok, error?}` result instead of raising; on any failure the tool returns (rather than raises) an error payload with `failed_ranges` and `written_ranges` (each with exact row boundaries) so the missing rows can be retried precisely, alongside the already-created `spreadsheetId`.
+
+### 12. Redundant per-sheet `get_modified_time()` call in `get_multiple_spreadsheet_summary`
+
+The per-sheet loop refetched `get_modified_time(drive_service, spreadsheet_id)` for every sheet, even though `modifiedTime` is a Drive *file-level* property — identical for every sheet tab in the same spreadsheet at a given instant. The original comment justified this as catching an edit that happened mid-request, but that race-window benefit is marginal compared to N redundant Drive API calls per spreadsheet (now each one a full `execute_in_thread` round trip). Deduplicated: `sheet_mtime` now reuses `current_mtime` captured once before the per-sheet loop.
+
+### 13. `get_multiple_spreadsheet_summary` was missing response-cap/`local_path` parity with its sibling
+
+`get_multiple_sheet_data` and `find_in_spreadsheet` both call `enforce_response_size_cap` and support a `local_path` bypass; `get_multiple_spreadsheet_summary` did neither, so a large enough batch could silently produce an oversized response with no safety net and no way to redirect it to disk. Added both, matching the sibling tools' contract exactly (`{local_path, spreadsheet_count, bytes_written}` manifest shape).
+
+### 14. Local-filesystem I/O sites still ran unwrapped on the event loop
+
+Three sites did blocking disk I/O directly in async tool bodies, with no `to_thread` wrap — harmless for small files but blocking the whole event loop for however long a large read/write takes, which specifically undermines the paths meant to handle *large* results: the CSV read in `import_csv_to_sheet` (`csv.reader` over the whole file), `write_capped_result_to_disk` (exists specifically to hold data too large for the response cap), and the single-shot `dest.write_bytes(content)` sites in `transfer.py`'s Workspace-file export paths (the chunked-download closures were already correctly wrapped). All three wrapped in `asyncio.to_thread`; `write_capped_result_to_disk` becoming `async def` required `await` at its 5 call sites (`sheets/data.py` ×4, `docs/content.py` ×1).
+
+### 15. Cache-invalidation race: a concurrent `refresh_cache()` could be silently undone
+
+`refresh_cache(spreadsheet_id=X)` calls `mark_dirty()`, which sets `dirty=1`. Every cache class's `store()` does `INSERT OR REPLACE ... dirty=0` unconditionally. Before #183, a tool call ran to completion on the event loop with no interleaving point, so a read-then-store sequence for a given key could never be interrupted by another call — this race genuinely could not happen. Now that reads have a real `await` (the `.execute()` call), a `refresh_cache()` call landing *during* another read's in-flight fetch for the same key has its `dirty=1` silently overwritten back to `dirty=0` once that read's `store()` runs afterward — erasing the invalidation's effect with no error or signal.
+
+**Fix:** an in-memory (not persisted — resets are fine, a fresh process has a fresh cache anyway), per-cache-instance monotonic epoch counter, bumped on every `mark_dirty`/`mark_all_dirty`. `_BaseCache` gained `snapshot_epoch()` (call before starting a fetch) and `_store_if_fresh(sql, params, epoch)` (skip the write entirely if the epoch changed between snapshot and store — i.e. an invalidation happened mid-fetch). Deliberately coarse (one counter per cache *instance*, not per-key): a concurrent invalidation for any key blocks in-flight stores for all keys in that cache, causing occasional spurious cache-miss refetches for unrelated keys rather than a precise per-key fix — a correctness-safe tradeoff against a full per-key generation-counter schema migration, scoped to the two caches actually touched by this PR's newly-concurrent code paths (`SheetStructureCache` via `fetch_sheets`/`get_multiple_spreadsheet_summary`, `SheetDataCache` via the latter's per-sheet loop). `store()` gained an optional `epoch: int | None = None` kwarg on both classes — omitting it (as every pre-existing caller does) preserves the old unconditional-write behavior exactly, so this is purely additive.
+
+DriveFolderCache/DocContentCache/CalendarCache's `store()` methods have the identical theoretical race (any tool call is now async, so *any* two calls can interleave, not just gather()'d ones) but weren't part of this fix — out of scope since their tools aren't part of this PR's newly-introduced concurrency and Sky's finding cited only the sheets-side call sites.
+
+### Round 2 verification
+
+- Full unit suite (674 tests, up from 665) green; `ruff check`/`ruff format --check` clean; zero unwrapped `.execute()` calls remain.
+- New regression tests: `test_server.py::TestAllToolsAreAsync` (enumerates every registered tool via `mcp._tool_manager.list_tools()` and asserts `inspect.iscoroutinefunction(inspect.unwrap(tool.fn))` — the exact check that caught #5 in round 1, now automated instead of a one-off manual introspection); `test_sharing.py`'s two `test_malformed_non_dict_entry_stays_attributable` tests; `test_files.py::test_partial_chunk_failure_reports_failed_and_written_ranges`; `test_cache.py`'s `test_store_with_stale_epoch_is_skipped`/`test_store_with_current_epoch_succeeds` pairs for both `SheetStructureCache` and `SheetDataCache`.
+- Live re-verification of TC-R36 (the concurrency bug's original reproduction) still needed from QA — not re-run live as part of this fix pass; see the "Dev note" appended to that test case in `docs/qa/tests/sheets_read.md`.

mcp_gee_sweet-0.7.0.dev93/docs/decisions/decision-dev-team.md

@@ -0,0 +1,38 @@
+# Decision: Named Dev-Team Roles with Isolated Worktrees + MCP Slots (issue #290)
+
+**Date:** 2026-07-11
+**Snapshot commit:** branch `feat/dev-team`
+
+## Background
+
+The existing `/orchestrator` workflow puts all post-implementation work — code review, live QA against real Google APIs, and merging — on one session (the main checkout), because live MCP tool calls only ever reach whatever code is checked out at a fixed filesystem path. `/verify-pr` works around this by fetching a worker's PR branch into a locally-named `review/<branch>` in the main checkout, testing it there, then pushing results back via a refspec. That workaround exists solely because nothing else can reach the branch's code live.
+
+The goal here is to let review/QA happen in its own dedicated, isolated worktree — in parallel, without occupying the main checkout — by giving each role its own persistent worktree and its own MCP server connection.
+
+## Decisions
+
+### 1. Five named roles, not generic "worker"/"reviewer" labels
+
+Kai (Orchestrator, main checkout), and two lanes each pairing a Dev and a QA agent: Ash/Sky (Lane A), Jay/Kit (Lane B). Short (≤3 character), gender-neutral names — easier for a human to scan and track at a glance than "worker-1"/"reviewer-2", and room to add personality later for anyone who wants a friendlier feel from the team, not just a bare label. Orchestrator sheds code review and live QA to the QA role; QA absorbs review, live testing, re-review, and sign-off. A lane runs at most one ticket at a time, which is what makes PR-to-lane routing unambiguous (decision 4).
+
+### 2. Persistent slots, not per-ticket worktrees
+
+The existing `/start-worktree`/`/next-issue` pattern creates a fresh worktree per ticket, removed after merge. Rejected for the four team roles: recreating a worktree (and its MCP server's `--directory`) every ticket would mean regenerating the MCP config on every cycle, and the whole point of naming these roles is a small fixed set of slots a human can track by name. Instead Ash/Sky/Jay/Kit each get one worktree that lives for the project's lifetime, resting on its own `team/<name>` branch and cycling: idle (`team/<name>`, at `origin/develop`) → active (checked out to a ticket/PR branch) → idle again after merge. `develop` itself is never checked out in a team-slot worktree — it's always checked out in the main checkout, so no other worktree can share that branch name.
+
+### 3. One combined MCP config, not one config per role
+
+The original framing assumed launching each role as its own `claude --mcp-config <role>.json --strict-mcp-config` process. Reconsidered once the actual usage pattern was clarified: this is driven from Claude Code's Agent View — one top-level `claude` invocation, then agents spawned from within it. A spawned agent always inherits whatever MCP servers its parent connected to at *its own* start; nothing spawned later can add a new connection, and there is no way to scope an already-running session down to a subset of its servers per-subagent. So five separate strict-mode processes doesn't fit — instead `.claude/mcp-configs/team.mcp.json` defines all six server entries (four role servers, Kai's own oauth/service-account pair, one shared `playwright`) side by side, loaded once. Every spawned agent can see every role's tools; the boundary is `/team-member` instructing each agent which prefix is its own, not a process wall. Accepted as a known tradeoff — worth revisiting (e.g. per-agent permission allow-lists) only if that discipline proves leaky in practice.
+
+### 4. Branch-name segment for lane routing, not a GitHub label or project board
+
+Dev branches are named `<type>/<devname>/issue-<n>`, inserting the name as the second `/`-separated segment ahead of the existing `<type>/issue-<n>` convention. `<type>` deliberately stays whatever this repo's convention already calls for given the ticket (checked against recent merged branches: `feat`, `fix`, `chore`, and `docs` all appear regularly) — it is *not* always `feat`, so routing must never assume that literal prefix. A QA agent finds its paired Dev's open PR by matching branch segment position, not a fixed string: `gh pr list --state open --json headRefName --jq 'select((.headRefName | split("/"))[1] == "<partner>")'`. Considered a `lane:a`/`lane:b` GitHub label instead — rejected as an extra piece of state to keep in sync for no real benefit, since the branch name already carries the same information and a lane only ever has one ticket in flight at a time (so the lookup is never ambiguous). The new `qa-approved` label *is* still used, but for sign-off state, not routing — routing needs no state at all beyond the branch name.
+
+### 5. `/cleanup-worktrees` must never touch the four team-slot worktrees
+
+Its existing rule — remove any worktree whose branch has a merged PR and is clean — would otherwise delete a team-slot worktree the moment its first ticket's PR merges, since a just-merged dev-team branch (e.g. `fix/ash/issue-241`) matches exactly that rule. Two changes: `/merge-pr`'s cleanup step now resets a team-slot worktree back to `team/<name>` in place (rather than removing the worktree) as soon as its PR merges, and `/cleanup-worktrees` itself unconditionally skips the four team-slot paths regardless of branch/PR state, as a second line of defense.
+
+## When to Re-evaluate
+
+- If the shared-MCP-config tool boundary (decision 3) turns out to be leaky in practice (an agent calling another role's tools by mistake), look at per-agent permission allow-lists rather than reintroducing per-role processes — Agent View's constraints haven't changed, so separate processes still won't fit the workflow.
+- If a third lane is ever added, the branch-prefix routing (decision 4) and the role table in `/team-member` both need a new row — there's no dynamic registry, this is a small hardcoded set by design.
+- If dev-team ticket volume grows past what two lanes can absorb, revisit whether Kai's own ticket-triage lane-assignment logic (in `/orchestrator`) still scales as a manual check, or needs to become closer to a real scheduler.

mcp_gee_sweet-0.7.0.dev93/docs/decisions/decision-release-docs-roles.md

@@ -0,0 +1,39 @@
+# Decision: Release QA Lead and Tech Writer Roles (issue #295)
+
+**Date:** 2026-07-12
+**Snapshot commit:** branch `feat/dev-team-2/issue-295`
+
+## Background
+
+[Dev-Team Roles](decision-dev-team.md) gave Ash/Sky (Lane A) and Jay/Kit (Lane B) persistent worktrees for per-ticket Dev/QA work. Two responsibilities don't fit that per-ticket shape: reviewing an entire release for correctness and documentation quality before it ships, and keeping documentation accurate/friendly/comprehensive on an ongoing basis. Both need their own isolated worktree to work independently of the two lanes, per the same rationale as decision-dev-team's decision 2.
+
+## Decisions
+
+### 1. Two more persistent slots, not a repurposed lane
+
+Aziz (release QA lead) and Amy (tech writer) each get a `team/<name>` worktree slot exactly like Ash/Sky/Jay/Kit — added to `scripts/setup_team.sh`'s worktree-provisioning loop and to the persistent-slot exclusion lists in `/merge-pr` and `/cleanup-worktrees` (now six names, not four). They are not a third lane: neither is Dev/QA-paired, both work at release or on-demand cadence rather than one-ticket-at-a-time, and the role table in `/team-member` reflects that with `—` for Lane and Partner.
+
+### 2. No dedicated MCP server for Aziz or Amy
+
+`scripts/setup_team.sh`'s `role_server` generation loop stays at four entries (Ash/Sky/Jay/Kit); Aziz and Amy are added to worktree provisioning only, not to that loop — no new `mcp-gee-sweet-aziz`/`mcp-gee-sweet-amy` server process starts. Both still receive the same combined `.mcp.json` copy every slot gets (per decision-dev-team's decision 3), so every server is visible in their tool list even though neither owns one. Amy's work is filesystem-only and doesn't need one. Aziz's live-QA work needs to call Sky's and Kit's tools directly (see decision 3) — giving him a server of his own would just be a second, redundant path to the same underlying MCP process each already runs, and the borrowed connection has the same in-session `.mcp.json` guarantee, so it costs nothing to skip.
+
+### 3. Aziz borrows Sky's/Kit's slots via `Agent`-tool subagents, not a new Playwright/API identity
+
+Live release QA needs the same real Google API + Playwright access Sky/Kit already have. Considered provisioning Aziz a third authenticated identity — rejected as unnecessary duplication of credentials and Playwright browser state for something that only runs periodically, at release time, when the dev team is idle by design (the user's explicit precondition: dev-team work and release QA never run concurrently). Instead Aziz resets Sky's and Kit's worktrees to `origin/develop` before a pass, then spawns `Agent`-tool subagents — true in-session subagents, which inherit whatever MCP servers their parent (Aziz's own session) is already connected to, per the established distinction from decision-dev-team's decision 3 fallout: this is different from an Agent-View "switch session" spawn, which does *not* inherit anything (confirmed live 2026-07-11, see `/team-member` §2). Each subagent is told which slot prefix (`mcp-gee-sweet-sky` or `mcp-gee-sweet-kit`) to call through and which domain/test file to run, mirroring the v0.8.1 QA pass's four-parallel-domain-shard structure. Subagents report structured PASS/FAIL back rather than editing any tracked file themselves — only Aziz, in his own worktree, writes the inline `**Result**` annotations, the aggregate results file, and the release sign-off doc, so two subagents running against Sky's and Kit's separately-checked-out worktrees never produce competing diffs to reconcile.
+
+### 4. QA-tier decision reuses the existing scoped-gating audit, made explicitly Aziz's call
+
+`docs/qa/runs/README.md` already documents a source-diff audit (enumerate commits, classify behavior-change vs. pure-refactor, map to domains, decide structural vs. non-structural) for when Full Regression can be substituted with Smoke + targeted Domain runs. Rather than inventing a separate process for "what does Aziz decide for a minor release," `/team-member`'s Aziz section points directly at that existing process and treats it as Aziz's responsibility to run and document per release, not a per-release ad hoc judgment call by whoever happens to be doing the release.
+
+### 5. Existing Playwright lockfile and no-fabricated-results conventions carry over unchanged
+
+Both were already established (`docs/qa/run.md` §"Coordinating Playwright across parallel shards"; the no-fabricated-results and repeat-live-verification disciplines from prior QA passes) and needed no new design — Aziz's subagents follow them exactly as any QA session would. Formalized in `/team-member` §5 rather than restated in a new doc.
+
+### 6. Amy claims work via a `documentation` label, mirroring `ready-for-development`
+
+Reuses the pre-existing `documentation` GitHub label rather than introducing a new one. Amy's PRs are not gated by `qa-approved` (that gate stays scoped to the four dev-lane names per decision-dev-team's decision 4) — normal `/merge-pr` review applies, since docs-only changes don't carry the same live-API regression risk that motivated the QA-approval gate for Dev-lane code.
+
+## When to Re-evaluate
+
+- If Aziz's borrowed-worktree model proves leaky (e.g. a subagent edits a tracked file despite instructions, or two shards collide on the same Playwright lock more than the backoff-retry tolerates), reconsider giving Aziz a dedicated Playwright/API identity after all — decision 3's rejection was based on avoided duplication for an infrequent workflow, not a hard constraint.
+- If Amy's doc-quality work starts needing live tool verification (not just static accuracy checks), reconsider whether she needs read-only access to a slot's MCP tools rather than staying filesystem-only (decision 2).

{mcp_gee_sweet-0.7.0.dev87 → mcp_gee_sweet-0.7.0.dev93}/docs/decisions/index.md

@@ -12,3 +12,6 @@ Point-in-time records of specific decisions — context, alternatives, and reaso
 | [Chart Theming and Phase 3 Integration](decision-chart-theming.md) | 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](decision-grid-data-size-cap.md) | 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](decision-cache-invalidation.md) | 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](decision-dev-team.md) | 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](decision-async-tool-execution.md) | 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](decision-release-docs-roles.md) | 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 |