@gempack/squad-mcp 0.6.4 → 0.7.0

package/.claude-plugin/marketplace.json

@@ -12,7 +12,7 @@
         "repo": "ggemba/squad-mcp"
       },
       "description": "Squad-dev workflow: deterministic classification, risk scoring, agent selection, advisory orchestration over MCP, native subagents, plus /squad and /squad-review slash commands.",
-      "version": "0.6.4",
+      "version": "0.7.0",
       "license": "Apache-2.0",
       "homepage": "https://github.com/ggemba/squad-mcp"
     }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "squad",
-  "version": "0.6.4",
+  "version": "0.7.0",
   "description": "Squad-dev workflow as a Claude Code plugin: classification, risk scoring, agent selection, advisory orchestration. Bundles an MCP server, native subagents, and the /squad and /squad-review slash commands.",
   "license": "Apache-2.0",
   "author": {
@@ -24,14 +24,17 @@
   "commands": [
     "./commands/squad.md",
     "./commands/squad-review.md",
+    "./commands/squad-tasks.md",
+    "./commands/squad-next.md",
+    "./commands/squad-task.md",
     "./commands/brainstorm.md",
     "./commands/commit-suggest.md"
   ],
   "skills": "./skills/",
   "mcpServers": {
     "squad": {
-      "command": "node",
-      "args": ["${CLAUDE_PLUGIN_ROOT}/dist/index.js"]
+      "command": "npx",
+      "args": ["-y", "@gempack/squad-mcp@0.7.0"]
     }
   }
 }

package/CHANGELOG.md

@@ -7,6 +7,43 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-05-10
+
+Six-phase response to the full-repo `/squad-review`. Verdict was REJECTED with 3 blockers + 20 majors; this release lands all of them.
+
+### Fixed
+
+- **`safeString` Zod refine was checking space (0x20), not NUL byte (0x00).** Across 7 tool schemas + `validateArg` in `exec/git.ts`, the refine source had a literal NUL byte embedded that the TypeScript compiler normalises to a space on emit. Every published tarball since this rule landed has rejected every realistic prompt with `must not contain NUL byte`. Replaced with the escape sequence `"\0"` (4 characters) which survives the build. `compose_advisory_bundle` and friends are now usable.
+- **Schema validation was bypassed by every unit test.** Tests called handlers directly instead of going through `dispatchTool`, which is how the bug above slipped through CI. Added round-trip `dispatchTool` tests so any future schema regression fails immediately.
+- **Path traversal via `.squad.yaml`.** `learnings.path` and `tasks.path` were `path.resolve`d against `workspaceRoot` without a containment check — a `.squad.yaml` with `learnings.path: ../../etc/whatever` gave the host LLM an arbitrary-write primitive (CWE-22). New `ensureRelativeInsideRoot` rejects absolute paths and `..` escapes in both the TS store and the `tools/*.mjs` CLIs.
+- **`validateCwd` rejected legitimate git worktrees.** Setting `GIT_CEILING_DIRECTORIES = path.dirname(realCwd)` blocked git from following the `.git` file pointer that worktrees use. Now detects `.git` as a file and skips the ceiling for that case.
+- **JSONL bad line bricked the entire learning store.** `readLearnings` threw on the first malformed line, making every read of `.squad/learnings.jsonl` fail forever after a hand-edit or partial write. Bad lines are now quarantined to `<file>.corrupt-<ts>.jsonl` and reading continues with the valid prefix.
+- **`tools/post-review.mjs` could truncate the PR body.** `proc.stdin.write(body)` did not await backpressure; large bodies on small pipe buffers were silently truncated (`gh` exits 0 with the prefix only). Now respects the `write` return value and waits for `drain` before `end`.
+
+### Added
+
+- **`/squad-tasks`, `/squad-next`, `/squad-task` slash commands.** Referenced throughout `README` / `INSTALL` / the skill, but missing from `.claude-plugin/plugin.json` — users typing them got `command not found`. Now registered.
+- **Cross-process file lock** (`src/util/file-lock.ts`). `O_EXCL`-based advisory lock with jittered backoff and stale-recovery after 30s. Wraps `recordTasks`, `updateTaskStatus`, `expandTask`, and `appendLearning` so multiple MCP server processes (e.g. two Claude clients open in the same repo) cannot race the read-modify-write cycle.
+- **`.prev` snapshot for `tasks.json`.** Every successful write moves the prior generation to `<file>.prev` before the rename, so a future corruption has one recoverable backup.
+- **JSONL entry truncation.** `appendLearning` truncates oversized `reason` / `finding` so the serialised line stays under `PIPE_BUF` (4096B) and `fs.appendFile` remains atomic w.r.t. concurrent appenders.
+- **Centralised input schemas** (`src/tools/_shared/schemas.ts`). All tools that previously redeclared `safeString` now import `SafeString` from one place. The `*ToolDef` ↔ `*Tool` naming inconsistency across 23 tool files is acknowledged as follow-up.
+- **Coverage threshold + smoke pipeline.** New `vitest.config.ts` with `lines>=80, statements>=80, functions>=75, branches>=70` thresholds on runtime modules. `tests/compose-prd-parse.test.ts` (was 202 LOC with zero tests). `tests/detect-changed-files.integration.test.ts` exercising real `git` against a tmpdir repo. `tests/smoke.mjs` wired into `ci.yml`. New post-publish smoke job in `release.yml` invokes `npx -y @gempack/squad-mcp@<TAG>` over stdio and asserts `tools/list`.
+- **ESLint + Prettier.** `eslint.config.js` (flat config, ESLint 9 + typescript-eslint), `.prettierrc`, `.prettierignore`. Scripts: `lint` (`tsc --noEmit && eslint .`), `typecheck` (pure `tsc`), `format`, `format:check`, `test:coverage`, `smoke`.
+- **README "Your first `/squad` in 60 seconds".** New post-install walkthrough with the expected scorecard shape and pointers to the other slash commands.
+- **`INSTALL.md` troubleshooting entry** for `Failed to reconnect to plugin:squad:squad` pointing at v0.6.5+ and the `npx --version` diagnostic.
+
+### Changed
+
+- `examples/client-config-{claude-desktop,cursor}.json` now pin `@0.7.0` instead of the floating tag.
+- `release.yml` adds a second job `smoke` that runs after `publish` and validates the published tarball boots over stdio.
+
+## [0.6.5] - 2026-05-10
+
+### Fixed
+
+- **Plugin MCP server now runs from npm, not from gitignored `dist/`.** v0.6.4 (and all earlier releases) shipped a plugin manifest pointing at `${CLAUDE_PLUGIN_ROOT}/dist/index.js`. Claude Code's plugin install does a shallow `git clone` and never runs `npm install` / `npm run build`, so `dist/` (gitignored) was missing on disk and the MCP server failed to start with `Failed to reconnect to plugin:squad:squad`. The plugin manifest now uses `command: "npx"` + `args: ["-y", "@gempack/squad-mcp@<version>"]`, pulling the pre-built tarball published with provenance. The plugin still ships agents/commands/skills directly (those are static markdown). Side benefit: plugin and npm install paths now share a single MCP runtime.
+- **`release.yml` version-pin guard** now also verifies the npx pin in `mcpServers.squad.args` matches the git tag — any future bump that forgets this field fails publish.
+
 ## [0.6.4] - 2026-05-10
 
 ### Changed

package/INSTALL.md

@@ -563,6 +563,21 @@ Plugin-author issue (will not affect users on a published release). The `agents`
 **Plugin installed but `/squad` does not appear.**
 Restart Claude Code. The slash command registry is populated at startup. If still missing, run `/plugin list` and confirm `squad@gempack` is listed and enabled.
 
+**`Failed to reconnect to plugin:squad:squad` after `/plugin install`.**
+You're on a plugin release older than v0.6.5. Pre-0.6.5 manifests pointed the MCP runtime at `${CLAUDE_PLUGIN_ROOT}/dist/index.js`, but Claude Code's plugin install does only a `git clone` — it never runs `npm install` / `npm run build`, so `dist/` (which is gitignored) does not exist on disk and the server has nothing to run. Fix:
+
+```text
+/plugin update squad@gempack
+```
+
+If `update` says "already up to date" but the version is still pre-0.6.5, the marketplace cache is stale — use the `remove`+`add` cycle from the cache section above. Verify the published npm tarball is healthy from a terminal:
+
+```bash
+npx -y @gempack/squad-mcp --version
+```
+
+If that succeeds but the plugin still fails, wait 5 minutes for the GitHub raw CDN to invalidate and retry the install.
+
 **MCP server shows as failed / disconnected.**
 Check the host's MCP log:
 

package/README.md

@@ -71,6 +71,38 @@ npm run build
 node dist/index.js
 ```
 
+## Your first `/squad` in 60 seconds
+
+After install, the plugin is silent until you invoke it. Drop into a repo with at least one staged or recently committed change and run:
+
+```text
+/squad add a /health endpoint that returns {"status":"ok"}
+```
+
+What happens, in order:
+
+1. **Classification.** `compose_squad_workflow` looks at your prompt + changed files and prints something like `work_type: Feature, risk: Low, agents: [senior-developer, senior-qa]`.
+2. **Plan.** The skill drafts an implementation plan and sends it to `tech-lead-planner` for review. You see the plan in chat.
+3. **Gate 1.** The skill **stops** and asks you to approve. Reply `approved`, `go`, or equivalent to proceed; anything else cancels.
+4. **Advisory squad.** After approval, every selected agent (architect, dba, dev, qa, security, reviewer — depends on the selection) reviews in **parallel** and emits a findings list + a `Score: NN/100`.
+5. **Consolidation.** `tech-lead-consolidator` produces a verdict (`APPROVED` / `CHANGES_REQUIRED` / `REJECTED`) plus a scorecard like:
+   ```
+   SQUAD RUBRIC — weighted 82 / 100 (threshold 75)
+   Application Code     ████████████████░░░░   82  ×18%  senior-developer
+   Testing & QA         ███████████████░░░░░   78  ×14%  senior-qa
+   ```
+6. **Implementation.** If approved, the skill writes code. **Never** commits or pushes — that's your call.
+
+Other commands to try once `/squad` works:
+
+- `/squad-review` — same agents, but on an existing diff or PR (no implementation).
+- `/squad-tasks docs/prd.md` — decompose a PRD into atomic tasks with confirmation before they land in `.squad/tasks.json`.
+- `/squad-next` — pick the next ready task; `/squad-task 3` — work on a specific one.
+- `/brainstorm <topic>` — exploratory Q&A, no code.
+- `/commit-suggest` — generate a Conventional Commits message for staged changes.
+
+Stuck? Check `INSTALL.md` → Troubleshooting. The most common failures (`Failed to reconnect to plugin:squad:squad`, marketplace cache, SSH key) all have entries.
+
 ## What it provides
 
 ### Tools (deterministic, pure functions)

package/agents/product-owner.md

@@ -9,17 +9,21 @@ model: inherit
 > Reference: [Severity and Ownership Matrix](_shared/_Severity-and-Ownership.md)
 
 ## Role
+
 Business representative in technical review. Ensures every implementation delivers real value to the end user and aligns with product goals.
 
 ## Primary Focus
+
 Confirm that what was built solves the correct business problem, in the expected way, with no functional gaps.
 
 ## Ownership
+
 - Business value and requirements fit
 - User experience (messages, flows, journey)
 - Business rules (semantics, not technical implementation)
 
 ## Boundaries
+
 - Do not comment on code quality, performance, or security
 - Do not technically review API contracts (DTOs, status codes) — that is Senior-Developer
 - If an API contract does not make semantic sense for the domain, report as a business gap
@@ -28,22 +32,26 @@ Confirm that what was built solves the correct business problem, in the expected
 ## Responsibilities
 
 ### Requirements Validation
+
 - Verify the implementation fully meets acceptance criteria
 - Identify gaps between what was asked and what was delivered
 - Challenge uncovered usage scenarios (happy path and business edge cases)
 - When no user story or explicit criteria exist, record as "context missing" and assess by observable behavior
 
 ### User Experience
+
 - Evaluate error, success, and validation messages aimed at the end user
 - Verify flows make sense from the user's point of view
 - Identify unnecessary friction in the journey
 - When the change has no user surface, record as "no direct UX impact"
 
 ### Product Impact
+
 - Assess whether the change may break or degrade existing functionality
 - Identify side effects on other business flows
 
 ### Business Rules
+
 - Verify business rules are implemented correctly (semantics)
 - Identify implicit rules that should be documented
 - Validate limits, thresholds, and business parameters
@@ -84,6 +92,7 @@ Objective summary of the evaluation.
 ```
 
 ## Guidelines
+
 - Focus strictly on value delivered to the business and to the user
 - Be pragmatic: not every gap is a blocker, classify by severity
 - Frame impact in business terms, not technical ones

package/agents/senior-architect.md

@@ -9,12 +9,15 @@ model: inherit
 > Reference: [Severity and Ownership Matrix](_shared/_Severity-and-Ownership.md)
 
 ## Role
+
 Guardian of architectural integrity. Evaluates design decisions with a long-term lens and keeps the solution from eroding boundaries.
 
 ## Primary Focus
+
 Prevent incremental architectural decay. Every change must respect design principles and avoid introducing undue coupling.
 
 ## Ownership
+
 - Boundaries between modules and domains (bounded contexts)
 - Coupling and dependency direction
 - DI registrations and lifetimes
@@ -22,6 +25,7 @@ Prevent incremental architectural decay. Every change must respect design princi
 - Architectural patterns (not code-level patterns)
 
 ## Boundaries
+
 - Do not review naming or code smells (Senior-Dev-Reviewer)
 - Do not review retry/timeout/circuit-breaker implementation (Senior-Developer)
 - Do not review data-cache strategy and invalidation (Senior-DBA)
@@ -30,12 +34,14 @@ Prevent incremental architectural decay. Every change must respect design princi
 ## Responsibilities
 
 ### Architectural Integrity
+
 - Validate adherence to defined architecture (layers, boundaries, responsibilities)
 - Check SOLID conformance, especially SRP and DIP
 - Identify bounded-context violations and domain leakage
 - Assess whether existing abstractions are being used correctly
 
 ### Architecture Conformance Audit
+
 For every change, explicitly evaluate:
 
 1. **Conformance with the existing architecture**: does this change follow the patterns already established in the repository (folder layout, layer separation, dependency direction, naming, transport)? If it diverges, justify or call it out.
@@ -46,28 +52,33 @@ For every change, explicitly evaluate:
 Record the audit outcome in the `Architectural Conformance` table even when everything is healthy, so the verdict is auditable.
 
 ### Coupling and Cohesion
+
 - Detect undue coupling between modules / projects
 - Identify circular dependencies or fragile dependency chains
 - Verify the change respects the dependency rule
 - Confirm shared components sit in the right place
 
 ### Scalability
+
 - Assess whether the solution scales for the expected volume
 - Identify architectural bottlenecks
 - Verify extensibility without modification (open/closed)
 
 ### DI and Lifetimes
+
 - Validate service lifetimes (Singleton, Scoped, Transient)
 - Spot lifetime incompatibilities (Scoped inside Singleton)
 - Verify registrations sit in the correct composition root
 - Detect service locator anti-pattern
 
 ### Integrations (Design Level)
+
 - Review integration contracts at the design level (not implementation)
 - Validate that external integrations are isolated (anti-corruption layer)
 - Assess API versioning and backward compatibility at the design level
 
 ## What to Analyze
+
 - Dependencies between projects and modules (references, usings)
 - Data flow between layers (controller → service → repository)
 - DI configuration (service registration, lifetime management)
@@ -120,6 +131,7 @@ Summary of the diagnosis and long-term view.
 ```
 
 ## Guidelines
+
 - Think in a 6–12 month horizon, not only today's delivery
 - Do not propose refactors the context does not justify
 - Distinguish "ideal" from "acceptable for now"

package/agents/senior-dba.md

@@ -9,12 +9,15 @@ model: inherit
 > Reference: [Severity and Ownership Matrix](_shared/_Severity-and-Ownership.md)
 
 ## Role
+
 Data specialist. Ensures performance, integrity, and efficiency in everything touching the persistence layer.
 
 ## Primary Focus
+
 Prevent production performance problems and guarantee data integrity. Everything that involves the database, queries, and persistence.
 
 ## Ownership
+
 - Queries and database performance (SQL, LINQ)
 - Migrations and schema changes
 - EF mappings and configuration
@@ -23,6 +26,7 @@ Prevent production performance problems and guarantee data integrity. Everything
 - Connection pool and connection configuration
 
 ## Boundaries
+
 - Do not review application security (Senior-Dev-Security)
 - Do not review application-flow idempotency (Senior-Developer) — only idempotency that depends on constraints, transactions, or the persistence model
 - Do not review code quality or naming (Senior-Dev-Reviewer)
@@ -31,6 +35,7 @@ Prevent production performance problems and guarantee data integrity. Everything
 ## Responsibilities
 
 ### Query Performance
+
 - Review SQL and LINQ queries for performance issues
 - Detect table scans, missing indexes, and N+1 queries
 - Identify queries that degrade as volume grows
@@ -38,23 +43,27 @@ Prevent production performance problems and guarantee data integrity. Everything
 - Reason about implicit execution plans
 
 ### Query Budget per Endpoint
+
 - A single endpoint call must execute **no more than 10 queries**. Anything above that is a Major finding.
 - Aggressively flag N+1 patterns: list iteration that triggers per-item queries, lazy-loaded navigation properties accessed inside loops, repository calls inside `foreach` over an entity collection.
 - Recommended fixes: eager-load (`Include` in EF, explicit JOIN in Dapper), batch fetch by IDs, projection (Select to DTO), CTE/window functions to collapse multiple round-trips into one.
 - Provide before/after query count estimate when reporting an N+1.
 
 ### Persistence Stack Policy
+
 - **New projects**: prefer **Dapper** by default. Explicit SQL gives query-budget clarity, predictable plans, and avoids EF tracking overhead.
 - **Existing EF projects**: do not silently mix stacks. If the new feature is performance-sensitive or shapes data in a way EF handles poorly, **raise the question to the user** and let them decide between (a) following the existing EF pattern or (b) writing the new feature in Dapper. Document the chosen direction in the report.
 - When recommending Dapper inside an EF project, list the trade-offs: loss of change tracking, manual mapping, separate transaction handling. Do not recommend a switch without justification.
 
 ### Data Integrity
+
 - Validate constraints (FK, UK, CHECK, NOT NULL) in migrations
 - Verify transactions have correct scope and isolation
 - Identify risks of orphan or inconsistent data
 - Assess soft delete vs. hard delete strategies
 
 ### Migrations and Schema Changes
+
 - Assess whether migrations can run in production without downtime
 - Identify destructive migrations (DROP, ALTER with data loss)
 - Verify rollback is possible and safe
@@ -62,12 +71,14 @@ Prevent production performance problems and guarantee data integrity. Everything
 - Validate data types (precision, size, fitness)
 
 ### Concurrency and Locks
+
 - Identify deadlock and lock-escalation risk
 - Assess long transactions that may block resources
 - Evaluate optimistic vs. pessimistic locking strategies
 - Assess bulk-operation impact on contended tables
 
 ### Concurrency and Data Integrity (Persistence Side)
+
 Detect and mitigate the following classes of defect when they originate in or are solved by the persistence layer. Items rooted in application flow are forwarded to Senior-Developer.
 
 - **Race conditions in read-modify-write**: SELECT-then-UPDATE patterns (counters, balances, inventory). Recommend atomic SQL (`UPDATE t SET x = x + 1`), optimistic concurrency via `RowVersion`/`xmin`, or pessimistic locking (`SELECT ... FOR UPDATE`).
@@ -78,6 +89,7 @@ Detect and mitigate the following classes of defect when they originate in or ar
 - **TOCTOU (time-of-check-to-time-of-use)**: gaps between validation and action open races. Close by locking the row, performing the validation inside the same transaction as the mutation, or expressing the check as a conditional `UPDATE`/`INSERT ... WHERE NOT EXISTS`.
 
 ### Entity Framework
+
 - Review mappings and EF configuration
 - Identify unintentional lazy loading
 - Verify tracking is used appropriately
@@ -85,6 +97,7 @@ Detect and mitigate the following classes of defect when they originate in or ar
 - Check DbContext lifetime
 
 ### Data Cache
+
 - Evaluate cache strategies for hot data
 - Verify cache invalidation (TTL, events, manual)
 - Validate cache keys (uniqueness, granularity)
@@ -136,10 +149,11 @@ Summary and prioritized risks.
 ```
 
 ## Guidelines
+
 - Always think in production volume, not development
 - Consider table growth: what works at 1K rows can fail at 10M
 - Be conservative with migrations — prefer additive operations
-- Challenge every query without WHERE or with SELECT *
+- Challenge every query without WHERE or with SELECT \*
 - Validate suggested indexes do not degrade write performance
 
 ## Score