@cyanheads/mcp-ts-core 0.8.0 → 0.8.2

package/skills/maintenance/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Investigate, adopt, and verify dependency updates — with special handling for `@cyanheads/mcp-ts-core`. Captures what changed, understands why, cross-references against the codebase, adopts framework improvements, syncs project skills, and runs final checks. Supports two entry modes: run the full flow end-to-end, or review updates you already applied.
 metadata:
   author: cyanheads
-  version: "1.8"
+  version: "2.0"
   audience: external
   type: workflow
 ---
@@ -50,6 +50,8 @@ Do not redo this investigation inline — the `changelog` skill handles tag-form
 
 ### 4. Framework review (`@cyanheads/mcp-ts-core`)
 
+**Skill-version paradox.** If `node_modules/@cyanheads/mcp-ts-core/skills/maintenance/SKILL.md`'s `version` exceeds the one running, run Step 5 Phase A first and re-invoke `maintenance` — otherwise feature-adoption rows added in the new version silently don't surface.
+
 If `@cyanheads/mcp-ts-core` was updated, do a deeper pass beyond what the `changelog` skill covers. The framework ships a **directory-based changelog** grouped by minor series (`.x` semver-wildcard convention) — one file per released version at `node_modules/@cyanheads/mcp-ts-core/changelog/<major.minor>.x/<version>.md`. Read only the files between old and new rather than scanning a monolithic file.
 
 Example — `0.5.2 → 0.5.4` means reading two new version files:
@@ -66,6 +68,7 @@ Scan specifically for:
 | Area | Adoption Check |
 |:-----|:---------------|
 | New `/errors` surface — factories, typed contracts (`errors[]` + `ctx.fail`), `httpErrorFromResponse` | Replace ad-hoc `new McpError(...)` with factories; declare `errors: [...]` on tools that surface domain-specific failure modes; route declared throws through `ctx.fail(reason, …)` so the conformance lint is happy |
+| Existing factory choice — semantic audit | Beyond factory-vs-`new McpError`: audit each `throw factory(...)` against intent. `invalidParams` (-32602) is for malformed JSON-RPC params (wrong-shape post-Zod is rare); semantic post-shape validation should use `validationError` (-32007). `notFound` for missing entities, `conflict` for state collisions, `unauthorized` vs `forbidden` for unauth vs scope-denied. Wrong codes degrade `mcp_error_classified_code` observability and break client retry logic — fix during this pass even if not adopting contracts yet. |
 | New utilities in `/utils` | Identify any that supersede local helper code |
 | New context capabilities | Added `ctx.*` methods worth adopting |
 | Provider/service APIs | Updates to `OpenRouterProvider`, `SpeechService`, `GraphService`, etc. |
@@ -145,16 +148,28 @@ If the consumer customized a framework script, the overwrite discards those chan
 
 Apply the findings from Steps 3 and 4. Framework changes and third-party library changes have different adoption defaults — the asymmetry is deliberate.
 
-**Framework changes (`@cyanheads/mcp-ts-core`) — default adopt.**
+**Framework changes (`@cyanheads/mcp-ts-core`) — auto-adopt every applicable site, in this pass.**
 
-The consumer opted into the framework; its templates, skills, scripts, linter rules, and conventions are authoritative. Adopt directly unless the change genuinely conflicts with a documented local override.
+The consumer opted into the framework; its templates, skills, scripts, linter rules, conventions, and new APIs that supersede local code are authoritative. Adopt them now — not as a follow-up.
 
 - **Breaking changes** — fix call sites. Not optional.
 - **Deprecations** — migrate now, while context is fresh.
 - **New linter rules** — if the rule now flags existing code, fix the code; don't silence the rule.
-- **New utilities that supersede local code** — swap them in. The point of the framework is to centralize.
+- **New utilities that supersede local code** — swap them in. The point of the framework is to centralize. This applies even when the local helper has richer messages or branch handling — port the domain detail onto the framework path; don't leave the local helper as-is. (E.g., `httpErrorFromResponse` replacing a project-local `throwForStatus`: keep the per-route message map, but route it through the framework utility.)
 - **New conventions** (template changes, new config keys, renamed env vars) — adopt and update `.env.example`, server config schema, `server.json`, and README if user-facing.
-- **New framework features that don't match existing use cases** — skip; those are for future features, not retroactive refactors.
+- **New patterns that match existing surfaces** — refactor *every* matching site in this pass. Examples: typed error contracts (`errors[]` + `ctx.fail`) on tools that already throw domain-specific failures; factory adoption (`notFound()`, `validationError()`, …) replacing ad-hoc `new McpError(...)`; new logging/observability hooks supplanting bespoke logging. If the framework added a pattern that fits N tools/services, do all N — partial adoption fragments the surface and rots faster.
+- **New framework features that don't match existing use cases** — skip. These are for future features, not retroactive refactors. "Don't match" means *the surface doesn't exist in this server* (e.g., a new Speech API in a non-speech server) — not "I'd have to touch a few files."
+
+**Hard rule — invalid framework deferrals.**
+
+| ❌ Not a valid reason to defer | ✅ Valid reason to defer |
+|:-------------------------------|:-------------------------|
+| "Larger change than fits this pass" | Code-commented or `CLAUDE.md`-documented local override that intentionally diverges from the framework convention |
+| "Marginal benefit / leaving as-is" | Breaking change with multiple migration paths that need user input |
+| "Per-tool refactor — worth doing as a focused follow-up" | Feature genuinely doesn't apply (the surface doesn't exist in this server) |
+| "Existing helper has rich domain messages we'd lose" | — (port the messages onto the framework path) |
+
+If you find yourself writing the left-column phrasing in Step 8's "Open decisions", stop and adopt it instead. Cost/benefit reasoning belongs to third-party changes only.
 
 **Third-party library changes — default cost/benefit.**
 
@@ -186,7 +201,7 @@ Present a concise numbered summary to the user:
 3. **Features adopted** — new framework APIs now in use
 4. **Skills synced** — added/updated with versions (Phase A) and agent directories refreshed (Phase B)
 5. **New/changed skills available** — skills that appeared in Phase A for the first time or had materially-changed step sequences. Frame as "consider running when the time is right" rather than immediate actions; the user decides when to invoke them.
-6. **Open decisions** — genuinely ambiguous items: breaking changes with multiple migration paths, framework changes that conflict with a documented local override, third-party adoptions where the cost/benefit is close
+6. **Open decisions** — genuinely ambiguous items only. Valid: breaking changes with multiple migration paths needing user input, framework changes that conflict with a code-commented or `CLAUDE.md`-documented local override, third-party adoptions where cost/benefit is close. **Not valid:** framework adoptions deferred for scope, effort, or marginal-benefit reasoning — those were already adopted in Step 6 and belong under "Features adopted." If this section is empty, that's the expected outcome of a clean framework upgrade.
 7. **Status** — rebuild / devcheck / test results
 
 ## Checklist
@@ -194,7 +209,7 @@ Present a concise numbered summary to the user:
 - [ ] Update applied (`bun update --latest`) — Mode A, or already done by user — Mode B
 - [ ] `changelog` skill invoked for each updated package
 - [ ] Framework CHANGELOG reviewed if `@cyanheads/mcp-ts-core` was updated
-- [ ] Adoption opportunities identified and applied
+- [ ] Every applicable framework adoption opportunity applied in this pass — no scope/effort/marginal-benefit deferrals; third-party adoptions evaluated on cost/benefit
 - [ ] Project `skills/` synced from package (Phase A), with a change report
 - [ ] Agent skill directories (`.claude/skills/`, `.agents/skills/`, etc.) refreshed from project `skills/` (Phase B)
 - [ ] Framework `scripts/` resynced from package via content-hash compare (Phase C), with a change report; `scripts/` diff reviewed before committing

package/templates/changelog/template.md

@@ -2,7 +2,7 @@
 # FORMAT REFERENCE — this file is never edited, never moved, never renamed.
 #
 # At release time, author a new per-version file at:
-#   changelog/<major.minor>.x/<version>.md   (e.g. changelog/0.1.x/0.1.0.md)
+#   changelog/<major.minor>.x/<version>.md   (e.g. changelog/0.6.x/0.6.6.md)
 # using this file's frontmatter and section layout as the starting point.
 # Set that new file's H1 to `# <version> — YYYY-MM-DD` with a concrete date.
 
@@ -27,16 +27,29 @@ breaking: false
 
   Optional narrative intro — 1-3 sentences framing the release theme. Delete if not needed.
 
+  TONE: terse and fact-dense. 1-2 sentence(s) per bullet where possible —
+  name the symbol, state what changed, stop. Drop "explains how it works" prose;
+  that belongs in JSDoc, AGENTS.md, or the relevant skill. Drop ceremonial
+  framings ("This release introduces…", "fully backwards compatible:" with a
+  paragraph of justification). Prefer code/symbol names over English
+  re-explanations. If a bullet runs more than ~2 lines, split it or cut it.
+
+  WHAT TO INCLUDE: every distinct fact a reader needs to adopt or audit the
+  release — new exports, signatures, lint rule IDs, env vars, breaking
+  changes, version bumps on shipped skills. WHAT TO CUT: mechanism walkthroughs,
+  duplicate prose between Added and Changed, file-by-file test enumerations,
+  internal implementation notes. Trust the reader to read the code or the docs.
+
   Linking issues/PRs: use full URLs so the link works everywhere (GitHub web UI,
   npm/node_modules reads, local editors). GitHub's bare `#NN` auto-link only
   resolves inside its own UI.
 
-    [#12](https://github.com/<owner>/<repo>/issues/12)   ← issue
-    [#17](https://github.com/<owner>/<repo>/pull/17)     ← PR
+    [#38](https://github.com/cyanheads/mcp-ts-core/issues/38)   ← issue
+    [#42](https://github.com/cyanheads/mcp-ts-core/pull/42)     ← PR
 
   Only link numbers you've verified exist (via `gh issue view NN` or
-  `gh pr view NN`). Never speculate on a future number — `#17` for "my
-  upcoming PR" will quietly resolve to whatever real item already owns 17,
+  `gh pr view NN`). Never speculate on a future number — `#42` for "my
+  upcoming PR" will quietly resolve to whatever real item already owns 42,
   and GitHub timeline previews will pull in that unrelated item's title.
 -->