@cyanheads/mcp-ts-core 0.13.7 → 0.13.9

package/framework-skills/report-issue-framework/SKILL.md

@@ -4,7 +4,7 @@ description: >
   File a bug or feature request against @cyanheads/mcp-ts-core when you hit a framework issue. Use when a builder, utility, context method, or config behaves contrary to the documented API — not for server-specific application bugs.
 metadata:
   author: cyanheads
-  version: "1.13"
+  version: "1.14"
   audience: external
   type: workflow
 ---
@@ -33,7 +33,8 @@ For general `gh` CLI workflows outside issue filing (PRs, workflows, API access)
 gh issue list -R cyanheads/mcp-ts-core --search "your error message or keyword" --state all
 
 # Assess a close match before commenting — is it already linked to a fix or referenced elsewhere?
-gh issue view <number> -R cyanheads/mcp-ts-core --comments
+gh issue view <number> -R cyanheads/mcp-ts-core              # body
+gh issue view <number> -R cyanheads/mcp-ts-core --comments   # thread only — without a TTY it prints no body
 gh api 'repos/cyanheads/mcp-ts-core/issues/<number>/timeline' --paginate \
   --jq '.[] | select(.event=="cross-referenced") | .source.issue | "\(.repository.full_name)#\(.number) — \(.title)"'
 ```
@@ -80,7 +81,7 @@ gh issue create -R cyanheads/mcp-ts-core \
   --body "$(cat <<'ISSUE'
 ### mcp-ts-core version
 
-0.1.29
+<installed version from node_modules/@cyanheads/mcp-ts-core/package.json — not the ^ range>
 
 ### Runtime
 
@@ -88,7 +89,7 @@ Bun
 
 ### Runtime version
 
-Bun 1.3.x
+<bun --version>
 
 ### Transport
 
@@ -249,7 +250,8 @@ ISSUE
 ## Following Up
 
 ```bash
-# Check issue status (with comment thread)
+# Check issue status, then its comment thread (--comments without a TTY prints no body)
+gh issue view <number> -R cyanheads/mcp-ts-core
 gh issue view <number> -R cyanheads/mcp-ts-core --comments
 
 # Add context or respond to maintainer questions

package/framework-skills/report-issue-local/SKILL.md

@@ -4,7 +4,7 @@ description: >
   File a bug or feature request against this MCP server's own repo. Use for server-specific issues — tool logic, service integrations, config problems, or domain bugs that aren't caused by the framework.
 metadata:
   author: cyanheads
-  version: "1.11"
+  version: "1.12"
   audience: external
   type: workflow
 ---
@@ -38,7 +38,8 @@ gh repo view --json nameWithOwner -q '.nameWithOwner'
 gh issue list --search "your error message or keyword" --state all
 
 # Assess a close match before commenting — is it already linked to a fix or referenced elsewhere?
-gh issue view <number> --comments
+gh issue view <number>              # body
+gh issue view <number> --comments   # thread only — without a TTY it prints no body
 gh api 'repos/{owner}/{repo}/issues/<number>/timeline' --paginate \
   --jq '.[] | select(.event=="cross-referenced") | .source.issue | "\(.repository.full_name)#\(.number) — \(.title)"'
 ```
@@ -87,11 +88,11 @@ gh issue create \
   --body "$(cat <<'ISSUE'
 ### Server version
 
-0.1.0
+<package.json version>
 
 ### mcp-ts-core version
 
-0.1.29
+<installed version from node_modules/@cyanheads/mcp-ts-core/package.json — not the ^ range>
 
 ### Runtime
 
@@ -99,7 +100,7 @@ Bun
 
 ### Runtime version
 
-Bun 1.3.x
+<bun --version>
 
 ### Transport
 
@@ -258,7 +259,8 @@ When genuinely ambiguous, file against this server's repo and note that it might
 ## Following Up
 
 ```bash
-# View issue details (with comment thread)
+# View the issue body, then its comment thread (--comments without a TTY prints no body)
+gh issue view <number>
 gh issue view <number> --comments
 
 # Add context

package/framework-skills/security-pass/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Review an MCP server for common security gaps: LLM-facing surfaces as injection vector (tools, resources, prompts, descriptions), scope blast radius, destructive ops without consent, upstream auth shape, input sinks (URL / path / roots / shell / schema strictness / ReDoS), tenant isolation, leakage through errors and telemetry, unbounded resources, and HTTP-mode deployment surface. Use before a release, after a batch of handler changes, or when the user asks for a security review, audit, or hardening pass. Produces grouped findings and a numbered options list.
 metadata:
   author: cyanheads
-  version: "1.10"
+  version: "1.11"
   audience: external
   type: audit
 ---
@@ -116,7 +116,7 @@ grep -rn "auth: \[" src/mcp-server/tools/definitions/
 
 ```bash
 grep -rn "destructiveHint" src/mcp-server/tools/definitions/
-grep -rn "ctx.requestInput\|ctx.inputs" src/mcp-server/tools/definitions/
+grep -rnE "ctx\.requestInput|ctx\.inputs" src/mcp-server/tools/definitions/
 ```
 
 **Check:**
@@ -127,7 +127,7 @@ grep -rn "ctx.requestInput\|ctx.inputs" src/mcp-server/tools/definitions/
 - Consent is scoped to the specific target (e.g., record ID rendered in the message), not a generic "proceed?"
 - Any `requestState` carried across rounds is integrity-protected if it influences authorization, resource access, or which target gets mutated. It round-trips through the client and comes back attacker-controlled; the SDK does not sign or verify it.
 - **A consent gate's state is server-issued and single-use.** A client can send `inputResponses` plus a `requestState` of its own on the very FIRST call — honored on 2025-era connections, even from a client that declared no `elicitation` — so a handler that only *compares* client-carried state against a fresh resolution deletes on a forged "accepted" answer without ever prompting. A signed state closes forgery but not replay within its TTL. Keep the confirmed target (plus a content hash, so a same-path swap is caught) in a server-side record keyed by a random id, send only the id, redeem it before anything else in the handler, and refuse an unknown, used, or expired id.
-- **The weak point is answerability, not availability.** `ctx.requestInput` is present on every transport and both protocol eras — the 2025-era shim issues the real `elicitation/create` round trip, the 2026-07-28 client fulfils the embedded request directly. A client that never retries simply leaves the destructive step un-run, which fails safe. Keep `destructiveHint: true` so client-side approval flows still surface the risk, and do not accept "proceed anyway when the round is unavailable" as a fallback — there is no such state to detect.
+- **The weak point is answerability, not availability.** `ctx.requestInput` is present on every transport and both protocol eras — the 2025-era shim issues the real `elicitation/create` round trip, the 2026-07-28 client fulfils the embedded request directly. A client that never retries simply leaves the destructive step un-run, which fails safe. Keep `destructiveHint: true` so client-side approval flows still surface the risk, and do not accept "proceed anyway when the round is unavailable" as a fallback. On a 2025-era connection whose client lacks the capability, `ctx.requestInput` throws `client_capability_missing` inside the handler; catching that to run the side effect is exactly this bypass — let it propagate.
 
 **Smell:** `destructiveHint: true` file with no `ctx.requestInput` in it. Or `ctx.inputs.accepted('confirm')` with no schema argument — the content could be anything. Or a handler that re-issues the same request after a `decline`.
 
@@ -157,22 +157,22 @@ LLM-supplied inputs feel internal but aren't. Classic sinks apply, amplified. Sa
 grep -rn "z.string().url()" src/
 
 # Path sinks — traversal
-grep -rn "readFile\|writeFile\|readdirSync\|createReadStream\|statSync" src/
+grep -rnE "readFile|writeFile|readdirSync|createReadStream|statSync" src/
 
 # Shell sinks — command injection
 grep -rnE "\b(exec|spawn|execSync|spawnSync)\b" src/
 
 # Merges — prototype pollution
-grep -rn "Object.assign\b\|structuredClone" src/
+grep -rnE "Object\.assign\b|structuredClone" src/
 
 # Lookups — prototype chain read through an object literal
 grep -rnE "\[[a-zA-Z_$][a-zA-Z0-9_$.]*\] *\?\? |\[[a-zA-Z_$][a-zA-Z0-9_$.]*\] *\|\| " src/
 
 # Roots — client-shared filesystem
-grep -rn "roots/list\|ctx.roots" src/
+grep -rnE "roots/list|ctx\.roots" src/
 
 # Schema laxity — fields sneaking past validation
-grep -rn "\.passthrough()\|\.loose()\|looseObject(\|\.catchall(" src/mcp-server/
+grep -rnE "\.passthrough\(\)|\.loose\(\)|looseObject\(|\.catchall\(" src/mcp-server/
 ```
 
 **Check:**
@@ -245,7 +245,7 @@ Unbounded = DoS of self, upstream, or the LLM's context window (billing-DoS is r
 
 ```bash
 grep -rnE "while\s*\(|for\s*\(.*of" src/mcp-server/tools/definitions/
-grep -rn "cursor\|nextPage\|paginate" src/
+grep -rnE "cursor|nextPage|paginate" src/
 grep -rn "JSON.parse\b" src/
 ```
 

package/framework-skills/techniques/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Catalog of reusable response- and data-shaping techniques for MCP servers built on `@cyanheads/mcp-ts-core` — overflow handling, payload shaping, retrieval patterns. Use when a tool's payload is too large, awkwardly shaped, or expensive to retrieve and you want a proven pattern instead of inventing one. Each technique has a self-contained reference under `references/`.
 metadata:
   author: cyanheads
-  version: "0.3"
+  version: "0.4"
   audience: external
   type: reference
 ---

package/framework-skills/techniques/references/outline-on-overflow.md

@@ -45,9 +45,12 @@ export const getLabel = tool('get_label', {
       .describe('Sections to return. Omit for the full label (or an outline if it overflows).'),
   }),
   output: z.object({
-    kind: z.enum(['full', 'outline']),
+    kind: z.enum(['full', 'outline']).describe('Whether the full label or a section outline was returned'),
     ...FullLabel.partial().shape,                         // full arm — every field optional
-    sections: OUTLINE_VARIANT.shape.sections.optional(),  // outline arm
+    sections: z                                           // outline arm
+      .array(OUTLINE_VARIANT.shape.sections.element.describe('One section of the label'))
+      .optional()
+      .describe('Available sections, largest first'),
     notice: OUTLINE_VARIANT.shape.notice.optional(),
   }),
   // Render each arm on field presence, independently — never branch on `kind` (see below).
@@ -66,6 +69,8 @@ export const getLabel = tool('get_label', {
 });
 ```
 
+The shape lints clean as written. The section item is described in place (`.element.describe(…)`, then the array re-described) because `describe-on-fields` asks every array-of-object element for a description and `OUTLINE_VARIANT`'s item carries none; folding `OUTLINE_VARIANT.shape.sections` in directly warns on `output.sections[]`. The `notice` beside a `sections` array is exempt from `enrichment-prefer-block` — it is the re-call instruction, main-body payload by design.
+
 `format()`-parity holds because every terminal field in `output` must appear in the rendered text. With a flat object the linter builds **one** synthetic sample with every optional field populated at once, so render each arm on field presence, independently — a mutually-exclusive `if (kind === 'outline') … else …` renders only one arm against that all-fields sample and fails parity for the other. `formatOutline` is the shipped renderer for the `outline` arm; you supply the `full` renderer. That keeps the two client surfaces in lockstep.
 
 ## The helper
@@ -75,9 +80,9 @@ export const getLabel = tool('get_label', {
 | Export | Purpose |
 |:--|:--|
 | `outlineOnOverflow(doc, options?)` | Returns `{ kind: 'full', ...doc }` under budget (or with `< 2` sections), else `{ kind: 'outline', sections, notice }`. |
-| `OUTLINE_VARIANT` | The reusable `outline`-arm Zod schema; fold `.shape.sections` / `.shape.notice` into your flat `output` object as optional arms. |
-| `selectSections(doc, want, { alwaysKeep })` | Projects the document to requested keys plus always-kept metadata. The selection-path counterpart. |
-| `formatOutline(outline)` | Renders the outline to `content[]` for `format()`. |
+| `OUTLINE_VARIANT` | The reusable `outline`-arm Zod schema; fold `.shape.sections` (item described in place, as above) / `.shape.notice` into your flat `output` object as optional arms. |
+| `selectSections(doc, want, { alwaysKeep })` | Projects the document to requested keys plus always-kept metadata. The selection-path counterpart. A requested name that is not a key of `doc` throws `InvalidParams`; the message names the unmatched names and the available keys, and `data` carries both (`unmatched`, `available`). An `alwaysKeep` key absent from `doc` is ignored. |
+| `formatOutline(outline)` | Renders the outline to `content[]` for `format()`. Each section name is a code span sized past any backtick in it, so the name reads back exactly as the caller must pass it in `sections`. |
 | `DEFAULT_OUTLINE_BUDGET_BYTES` | The default budget (`24_000`) when `options.budget` is omitted. |
 
 `outlineOnOverflow` options:
@@ -93,14 +98,14 @@ The flow:
 3. **Over budget, ≥ 2 sections** → the outline (sections sorted largest-first). The agent re-calls with `sections: [...]`.
 4. **Over budget, < 2 sections** → `full` anyway (nothing to pick between). A single section that *alone* exceeds budget is a known limitation — sub-section outlining is out of scope.
 
-The budget bounds the **disclosure**, not the selection. `selectSections` returns whatever the agent named, so a selection over several sections — or one section larger than the budget — comes back whole. That is deliberate: the agent asked for those sections by name, and truncating the answer is the thing this technique exists to avoid. The default notice reports each example's size so the selection can be sized before it is made.
+The budget bounds the **disclosure**, not the selection. `selectSections` returns whatever the agent named, so a selection over several sections — or one section larger than the budget — comes back whole. That is deliberate: the agent asked for those sections by name, and truncating the answer is the thing this technique exists to avoid. The default notice reports each example's size so the selection can be sized before it is made. The selection is not lenient about names, though: a name the document does not carry is rejected with the valid names, not dropped, so a stale or mistyped section never comes back as a quietly smaller answer.
 
 ## Re-retrieval — why the selection call is stateless
 
 The re-call is **self-contained**, so nothing is stored between the outline call and the selection call:
 
 - The selection call sends the **same input** as the outline call, plus `sections: [...]`.
-- The handler **re-fetches** the document — input-minus-`sections` is identical and the upstream query is deterministic, so it reproduces the exact same record — then applies `selectSections` (a pure projection: requested keys + `alwaysKeep` metadata).
+- The handler **re-fetches** the document — input-minus-`sections` is identical and the upstream query is deterministic, so it reproduces the exact same record — then applies `selectSections` (a pure projection: requested keys + `alwaysKeep` metadata; an unknown requested name throws `InvalidParams` naming the available keys).
 - You **reconstruct rather than remember**. The agent holds the continuity (it passes `sections`); the upstream holds the document.
 
 The only cost is the redundant fetch. For a **rate-limited or expensive upstream**, trade it for an optional cache:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.13.7",
+  "version": "0.13.9",
   "mcpName": "io.github.cyanheads/mcp-ts-core",
   "description": "Agent-native TypeScript framework for MCP servers. Includes runtime infrastructure and agent skills for building, testing, and shipping servers.",
   "files": [
@@ -201,18 +201,21 @@
     "@cloudflare/workers-types": "5.20260922.1",
     "@duckdb/node-api": "^1.5.5-r.5",
     "@hono/otel": "^1.1.2",
-    "@modelcontextprotocol/client": "^2.0.0",
+    "@modelcontextprotocol/client": "^2.1.0",
+    "@opentelemetry/api-logs": "^0.222.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.222.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.222.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.222.0",
     "@opentelemetry/instrumentation-http": "^0.222.0",
     "@opentelemetry/instrumentation-pino": "^0.68.0",
     "@opentelemetry/resources": "^2.11.0",
+    "@opentelemetry/sdk-logs": "^0.222.0",
     "@opentelemetry/sdk-metrics": "^2.11.0",
     "@opentelemetry/sdk-node": "^0.222.0",
     "@opentelemetry/sdk-trace-node": "^2.11.0",
     "@opentelemetry/semantic-conventions": "^1.43.0",
     "@socketsecurity/bun-security-scanner": "^1.1.3",
-    "@supabase/supabase-js": "^2.117.0",
+    "@supabase/supabase-js": "^2.117.1",
     "@types/bun": "^1.4.2",
     "@types/node": "26.6.2",
     "@types/papaparse": "^5.5.2",
@@ -232,7 +235,7 @@
     "js-yaml": "^5.4.2",
     "linkedom": "^0.18.13",
     "node-cron": "^4.6.0",
-    "openai": "^7.21.0",
+    "openai": "^7.23.0",
     "papaparse": "^5.7.0",
     "partial-json": "^0.1.7",
     "pdf-lib": "^1.17.1",
@@ -287,7 +290,7 @@
   },
   "dependencies": {
     "@hono/node-server": "^2.1.1",
-    "@modelcontextprotocol/server": "^2.0.0",
+    "@modelcontextprotocol/server": "^2.1.0",
     "@opentelemetry/api": "^1.9.1",
     "hono": "^4.13.8",
     "jose": "^6.2.12",
@@ -297,11 +300,14 @@
   "peerDependencies": {
     "@duckdb/node-api": "^1.5.5-r.1",
     "@hono/otel": "^1.1.2",
+    "@opentelemetry/api-logs": "^0.222.0",
+    "@opentelemetry/exporter-logs-otlp-http": "^0.222.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.222.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.222.0",
     "@opentelemetry/instrumentation-http": "^0.222.0",
     "@opentelemetry/instrumentation-pino": "^0.68.0",
     "@opentelemetry/resources": "^2.10.0",
+    "@opentelemetry/sdk-logs": "^0.222.0",
     "@opentelemetry/sdk-metrics": "^2.10.0",
     "@opentelemetry/sdk-node": "^0.222.0",
     "@opentelemetry/sdk-trace-node": "^2.10.0",
@@ -332,6 +338,12 @@
     "@hono/otel": {
       "optional": true
     },
+    "@opentelemetry/api-logs": {
+      "optional": true
+    },
+    "@opentelemetry/exporter-logs-otlp-http": {
+      "optional": true
+    },
     "@opentelemetry/instrumentation-http": {
       "optional": true
     },
@@ -347,6 +359,9 @@
     "@opentelemetry/resources": {
       "optional": true
     },
+    "@opentelemetry/sdk-logs": {
+      "optional": true
+    },
     "@opentelemetry/sdk-metrics": {
       "optional": true
     },

package/scripts/check-skill-versions.ts

@@ -20,10 +20,19 @@
  *
  * A bare name (`add-tool`) and the file path (`add-tool/SKILL.md`) both match.
  *
- * Diffing against `HEAD` keeps the per-release-cycle carve-out automatic: once the
- * version line is bumped, later commits in the same cycle no longer re-trigger.
+ * In the framework repo, a skill whose version already moved since the last `v*`
+ * release tag — or that is new since it — is covered: a later body edit in the
+ * same cycle shares that bump instead of needing another.
+ *
+ * The inverse also holds: a skill moves at most one step per release. In the
+ * framework repo itself, each skill's version is compared with its version at the
+ * last `v*` release tag, and anything past the next minor (`1.4` → `1.5`) or the
+ * next major (`1.4` → `2.0`) is a violation — repeated edits in one cycle share a
+ * single bump. Consumer repos skip this: a skill sync can legitimately jump
+ * several framework releases at once.
+ *
  * Severity mirrors `check-skills-sync.ts` — exits 1, demoted to a warning by
- * devcheck. New skills (no `HEAD` version) and non-git trees are skipped.
+ * devcheck. New skills (no prior version) and non-git trees are skipped.
  *
  * Runs standalone (`bun run scripts/check-skill-versions.ts`) and as a devcheck step.
  *
@@ -36,6 +45,7 @@ import process from 'node:process';
 
 const ROOT = resolve('.');
 const SKILL_MD_RE = /^framework-skills\/[^/]+\/SKILL\.md$/;
+const FRAMEWORK_PACKAGE = '@cyanheads/mcp-ts-core';
 
 interface DevcheckConfig {
   skillVersions?: { ignore?: string[] };
@@ -60,10 +70,10 @@ function isIgnored(relPath: string, patterns: string[]): boolean {
   );
 }
 
-/** Skill `SKILL.md` files that differ from `HEAD` (staged + unstaged). */
-function changedSkillFiles(): string[] {
-  const result = spawnSync('git', ['diff', '--name-only', 'HEAD', '--'], { encoding: 'utf-8' });
-  if (result.status !== 0) return []; // not a git repo / no HEAD commit
+/** Skill `SKILL.md` files that differ from `ref` in the working tree (staged + unstaged). */
+function changedSkillFiles(ref: string): string[] {
+  const result = spawnSync('git', ['diff', '--name-only', ref, '--'], { encoding: 'utf-8' });
+  if (result.status !== 0) return []; // not a git repo / no such ref
   return result.stdout
     .trim()
     .split('\n')
@@ -71,18 +81,50 @@ function changedSkillFiles(): string[] {
 }
 
 /**
- * Content of a path at `HEAD`, or null when it didn't exist there (new file).
- * A tree renamed from the pre-0.13 `skills/` reads its `HEAD` copy from the old
+ * Content of a path at `ref`, or null when it didn't exist there (new file).
+ * A tree renamed from the pre-0.13 `skills/` reads its old copy from the old
  * path, so the release that carries the rename still checks every body edit.
  */
-function headContent(relPath: string): string | null {
-  const show = (p: string) => spawnSync('git', ['show', `HEAD:${p}`], { encoding: 'utf-8' });
+function contentAt(ref: string, relPath: string): string | null {
+  const show = (p: string) => spawnSync('git', ['show', `${ref}:${p}`], { encoding: 'utf-8' });
   const result = show(relPath);
   if (result.status === 0) return result.stdout;
   const legacy = show(relPath.replace(/^framework-skills\//, 'skills/'));
   return legacy.status === 0 ? legacy.stdout : null;
 }
 
+/** True when this tree is the framework itself, where skill versions are authored. */
+function isFrameworkRepo(): boolean {
+  try {
+    const pkg = JSON.parse(readFileSync(resolve(ROOT, 'package.json'), 'utf-8')) as {
+      name?: string;
+    };
+    return pkg.name === FRAMEWORK_PACKAGE;
+  } catch {
+    return false;
+  }
+}
+
+/** The latest `v*` release tag reachable from `HEAD`, or null when there is none. */
+function lastReleaseTag(): string | null {
+  const result = spawnSync('git', ['describe', '--tags', '--abbrev=0', '--match', 'v*'], {
+    encoding: 'utf-8',
+  });
+  return result.status === 0 ? result.stdout.trim() : null;
+}
+
+/** True when `to` is `from`, its next minor, or its next major at `.0`. */
+function withinOneStep(from: string, to: string): boolean {
+  const [fromMajor, fromMinor] = from.split('.').map(Number);
+  const [toMajor, toMinor] = to.split('.').map(Number);
+  if ([fromMajor, fromMinor, toMajor, toMinor].some((n) => n === undefined || Number.isNaN(n))) {
+    return true; // not `X.Y` — out of this check's scope
+  }
+  if (from === to) return true;
+  if (toMajor === fromMajor) return toMinor === (fromMinor as number) + 1;
+  return toMajor === (fromMajor as number) + 1 && toMinor === 0;
+}
+
 /** `metadata.version` from skill frontmatter, or null when absent/unparseable. */
 function extractVersion(content: string): string | null {
   const block = content.match(/^---\n([\s\S]*?)\n---/)?.[1];
@@ -108,11 +150,24 @@ if (!existsSync(resolve(ROOT, 'framework-skills'))) {
 }
 
 const ignore = loadIgnorePatterns();
-const changed = changedSkillFiles().filter((f) => !isIgnored(f, ignore));
+const tag = isFrameworkRepo() ? lastReleaseTag() : null;
 
-const violations: { file: string; version: string }[] = [];
-for (const file of changed) {
-  const oldContent = headContent(file);
+/**
+ * True when the skill's current version already differs from its version at the
+ * release tag — or the skill is new since it — so this cycle's one step is taken
+ * and a further body edit shares it rather than needing another bump.
+ */
+function bumpedThisRelease(file: string, version: string | null): boolean {
+  if (tag === null) return false;
+  const released = contentAt(tag, file);
+  if (released === null) return true;
+  const releasedVersion = extractVersion(released);
+  return releasedVersion !== null && releasedVersion !== version;
+}
+
+const missing: { file: string; version: string }[] = [];
+for (const file of changedSkillFiles('HEAD').filter((f) => !isIgnored(f, ignore))) {
+  const oldContent = contentAt('HEAD', file);
   if (oldContent === null) continue; // new skill — no prior version to compare
   if (!existsSync(resolve(ROOT, file))) continue; // deleted in worktree — no body to compare, can't violate
   const newContent = readFileSync(resolve(ROOT, file), 'utf-8');
@@ -121,25 +176,51 @@ for (const file of changed) {
 
   const oldVersion = extractVersion(oldContent);
   const newVersion = extractVersion(newContent);
-  if (oldVersion !== null && oldVersion === newVersion) {
-    violations.push({ file, version: oldVersion });
+  if (oldVersion !== null && oldVersion === newVersion && !bumpedThisRelease(file, newVersion)) {
+    missing.push({ file, version: oldVersion });
   }
 }
 
-if (violations.length === 0) {
+const overshot: { file: string; tag: string; released: string; version: string }[] = [];
+if (tag !== null) {
+  for (const file of changedSkillFiles(tag)) {
+    const released = contentAt(tag, file);
+    if (released === null || !existsSync(resolve(ROOT, file))) continue;
+    const releasedVersion = extractVersion(released);
+    const version = extractVersion(readFileSync(resolve(ROOT, file), 'utf-8'));
+    if (releasedVersion === null || version === null) continue;
+    if (!withinOneStep(releasedVersion, version)) {
+      overshot.push({ file, tag, released: releasedVersion, version });
+    }
+  }
+}
+
+const count = missing.length + overshot.length;
+if (count === 0) {
   console.log('Skill versions are in step with body changes.');
   process.exit(0);
 }
 
 const lines = [
-  `${violations.length} skill${violations.length === 1 ? '' : 's'} changed body without a metadata.version bump:`,
+  `${count} skill${count === 1 ? '' : 's'} out of step with the versioning policy:`,
   '',
 ];
-for (const v of violations) {
+for (const v of missing) {
   lines.push(`  - ${v.file} body changed but metadata.version is still "${v.version}"`);
 }
+for (const v of overshot) {
+  lines.push(
+    `  - ${v.file} is "${v.version}", more than one step past "${v.released}" at ${v.tag}`,
+  );
+}
 lines.push('');
-lines.push('Fix: bump metadata.version in the SKILL.md frontmatter, or add the skill to');
-lines.push('     devcheck.config.json `skillVersions.ignore` for the typo/whitespace carve-out.');
+if (missing.length > 0) {
+  lines.push('Fix: bump metadata.version in the SKILL.md frontmatter, or add the skill to');
+  lines.push('     devcheck.config.json `skillVersions.ignore` for the typo/whitespace carve-out.');
+}
+if (overshot.length > 0) {
+  lines.push('Fix: set metadata.version to one step past the release tag — edits in one');
+  lines.push('     release cycle share a single bump.');
+}
 console.log(lines.join('\n'));
 process.exit(1);

package/scripts/devcheck.ts

@@ -711,12 +711,12 @@ const ALL_CHECKS: Check[] = [
     canFix: false,
     // Validates env var alignment between manifest.json (MCPB bundle) and
     // server.json (MCP Registry), plus plugin marketplace manifests (#240), the
-    // bundle-content guards on .mcpbignore (#343), and the README version badge
-    // (#418). Runs when any of those inputs is present; skipped cleanly when
-    // none exist — consumers on an HTTP-only deploy are unaffected. README.md is
-    // a trigger in its own right: the badge check must gate a project that
-    // carries no bundle or plugin metadata at all, which the other three inputs
-    // only covered incidentally.
+    // bundle-content guards on .mcpbignore (#343), the README version badge
+    // (#418), and the Dockerfile build platform. Runs when any of those inputs
+    // is present; skipped cleanly when none exist — consumers on an HTTP-only
+    // deploy are unaffected. README.md and Dockerfile are triggers in their own
+    // right: each check must gate a project that carries no bundle or plugin
+    // metadata at all, which the other inputs only covered incidentally.
     getCommand: () => {
       const inputs = [
         'manifest.json',
@@ -725,6 +725,7 @@ const ALL_CHECKS: Check[] = [
         '.codex-plugin/mcp.json',
         '.mcpbignore',
         'README.md',
+        'Dockerfile',
       ];
       if (!inputs.some((input) => existsSync(path.join(ROOT_DIR, input)))) return null;
       return ['bun', 'run', 'scripts/lint-packaging.ts'];
@@ -811,7 +812,8 @@ const ALL_CHECKS: Check[] = [
     flag: '--no-skill-versions',
     canFix: false,
     // Flags framework-skills/<name>/SKILL.md body changes (vs HEAD) that lack a metadata.version
-    // bump (#99). Skipped when framework-skills/ is absent. Drift is demoted to a warning via
+    // bump (#99), and, in the framework repo, a skill bumped more than one step past the last
+    // release tag. Skipped when framework-skills/ is absent. Drift is demoted to a warning via
     // isSuccess — the typo/whitespace carve-out lives in devcheck.config.json
     // `skillVersions.ignore`.
     getCommand: () => {
@@ -821,11 +823,11 @@ const ALL_CHECKS: Check[] = [
     isSuccess: (result) => {
       if (result.exitCode === 0) return true;
       const firstLine =
-        result.stdout.split('\n')[0]?.trim() || 'Skill bodies changed without a version bump.';
+        result.stdout.split('\n')[0]?.trim() || 'Skill versions are out of step with the policy.';
       return { success: true, warning: firstLine };
     },
     tip: (c) =>
-      `Bump ${c.bold('metadata.version')} in the changed ${c.bold('SKILL.md')}, or add it to ${c.bold('devcheck.config.json')} ${c.bold('skillVersions.ignore')}.`,
+      `Bump ${c.bold('metadata.version')} once per release in the changed ${c.bold('SKILL.md')}, or add it to ${c.bold('devcheck.config.json')} ${c.bold('skillVersions.ignore')}.`,
   },
   {
     name: 'Changelog Sync',