@witchpot/gmc 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to the Game Market Copilot CLI will be recorded here.
 
+## 0.5.0 - 2026-07-13
+
+- gmc-analysis skill v0.5.0 (NAK-190): new "Saved Game Lists" guidance in
+  SKILL.md and recipe R5 (reusable cohorts via `gmc lists ...` / the MCP
+  Game List tools / `game_list_id` and `--list <id>` inputs), plus a skill
+  changelog entry retroactively documenting the chart-card guidance that
+  shipped unversioned in CLI 0.4.0-era updates (new chart types, capsule
+  rows, export geometry, label placement, embedded brand typography).
+- New skill content-hash manifest guard: `npm run skill:manifest`
+  regenerates `skill/gmc-analysis.manifest.json`;
+  `src/skill-manifest.test.js` (runs in `npm test` / repo `verify`) and
+  `release:check` both fail when skill content changes without a version
+  bump and manifest regeneration, so the bundled skill and the public
+  gmc-agent-skills distribution repo can no longer drift silently.
+
 ## 0.4.0 - 2026-07-09
 
 - gmc-analysis skill v0.4.0: new `references/validity.md` with the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@witchpot/gmc",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "private": false,
   "description": "Command line tools for Game Market Copilot market research.",
   "license": "UNLICENSED",
@@ -43,6 +43,7 @@
   },
   "scripts": {
     "test": "node --test src/*.test.js",
+    "skill:manifest": "node scripts/gen-skill-manifest.mjs",
     "release:check": "node scripts/check-release-readiness.mjs && node scripts/smoke-pack.mjs",
     "prepublishOnly": "npm run release:check",
     "smoke:beta": "node scripts/smoke-beta.mjs",

package/scripts/check-release-readiness.mjs

@@ -122,6 +122,25 @@ for (const file of sourceFiles) {
   }
 }
 
+// The skill content-hash manifest (NAK-190) is also enforced by
+// src/skill-manifest.test.js, but release:check/prepublishOnly run WITHOUT
+// the test suite — recheck here so a stale manifest can never reach npm.
+const { buildSkillManifest, MANIFEST_PATH } = await import("./gen-skill-manifest.mjs");
+if (!existsSync(MANIFEST_PATH)) {
+  failures.push("skill/gmc-analysis.manifest.json is missing — run npm run skill:manifest.");
+} else {
+  const committedManifest = JSON.parse(readFileSync(MANIFEST_PATH, "utf8"));
+  const currentManifest = buildSkillManifest();
+  if (
+    committedManifest.contentHash !== currentManifest.contentHash ||
+    committedManifest.version !== currentManifest.version
+  ) {
+    failures.push(
+      "skill/gmc-analysis.manifest.json is stale: bump metadata.version in SKILL.md, run npm run skill:manifest, and re-sync the gmc-agent-skills distribution repo."
+    );
+  }
+}
+
 // The public distribution repo (github.com/witchpot-studio/gmc-agent-skills)
 // mirrors skill/gmc-analysis. When it is checked out as a workspace sibling,
 // a drift between the two is a release blocker — MCP-only users install the

package/scripts/gen-skill-manifest.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+
+// Regenerates skill/gmc-analysis.manifest.json — a content-hash fingerprint
+// of the packaged gmc-analysis skill (SKILL.md + references/ + CHANGELOG.md).
+//
+// Maintainer rule: any time skill/gmc-analysis/** content changes, bump
+// metadata.version in SKILL.md, then run `npm run skill:manifest` (in
+// packages/gmc-cli) to regenerate this manifest, and re-sync the
+// gmc-agent-skills distribution repo (node scripts/sync-from-cli.mjs there).
+// src/skill-manifest.test.js recomputes the same hash on every
+// `npm run test:cli` / `npm run verify` and fails loudly if it no longer
+// matches the committed manifest — this is the drift guard that would have
+// caught the unversioned charts.md changes in PR #18 / PR #43 (NAK-190).
+//
+// The manifest is written OUTSIDE skill/gmc-analysis/ on purpose: that
+// directory is mirrored byte-for-byte into the public gmc-agent-skills
+// distribution repo, and the manifest must never be part of (or affect the
+// hash of) the content it describes.
+
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageDir = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+export const SKILL_DIR = path.join(packageDir, "skill", "gmc-analysis");
+export const MANIFEST_PATH = path.join(packageDir, "skill", "gmc-analysis.manifest.json");
+
+/** List every file under `dir`, as sorted relative POSIX paths. */
+export function listSkillFiles(dir = SKILL_DIR) {
+  const results = [];
+  walk(dir, dir, results);
+  return results.sort();
+}
+
+function walk(root, current, results) {
+  const entries = readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+  for (const entry of entries) {
+    const abs = path.join(current, entry.name);
+    if (entry.isDirectory()) {
+      walk(root, abs, results);
+    } else if (entry.isFile()) {
+      results.push(path.relative(root, abs).split(path.sep).join("/"));
+    }
+  }
+}
+
+function sha256Hex(buffer) {
+  return createHash("sha256").update(buffer).digest("hex");
+}
+
+/**
+ * Hash every file under `dir` and fold the per-file hashes into one
+ * top-level sha256 over `relpath\nfilehash\n` lines (sorted, deterministic).
+ */
+export function computeSkillContentHash(dir = SKILL_DIR) {
+  const files = listSkillFiles(dir);
+  const digest = createHash("sha256");
+  for (const relPath of files) {
+    const fileHash = sha256Hex(readFileSync(path.join(dir, relPath)));
+    digest.update(`${relPath}\n${fileHash}\n`);
+  }
+  return { contentHash: digest.digest("hex"), files: files.length };
+}
+
+/** Parse metadata.version out of SKILL.md source text; undefined when absent. */
+export function parseSkillVersion(source) {
+  const frontmatter = source.match(/^---\n([\s\S]*?)\n---/);
+  return frontmatter?.[1].match(/^\s*version:\s*"?([0-9][0-9A-Za-z.\-]*)"?\s*$/m)?.[1];
+}
+
+/** Read metadata.version from SKILL.md's YAML frontmatter. */
+export function readSkillManifestVersion(dir = SKILL_DIR) {
+  const version = parseSkillVersion(readFileSync(path.join(dir, "SKILL.md"), "utf8"));
+  if (!version) {
+    throw new Error(`${path.join(dir, "SKILL.md")} must declare metadata.version in its frontmatter.`);
+  }
+  return version;
+}
+
+/** Build the manifest object (version + contentHash + files) for `dir`. */
+export function buildSkillManifest(dir = SKILL_DIR) {
+  const { contentHash, files } = computeSkillContentHash(dir);
+  return { version: readSkillManifestVersion(dir), contentHash, files };
+}
+
+/**
+ * Baseline manifest for the version-bump rule. The authoritative baseline is
+ * the manifest COMMITTED ON origin/main (read via `git show`, so deleting or
+ * hand-editing the local file cannot dodge the rule); the local file is only
+ * a fallback for environments where the git baseline is unreadable.
+ */
+function baselineSkillManifest() {
+  const result = spawnSync("git", ["show", "origin/main:packages/gmc-cli/skill/gmc-analysis.manifest.json"], {
+    cwd: packageDir,
+    encoding: "utf8"
+  });
+  if (result.status === 0 && typeof result.stdout === "string") {
+    try {
+      return JSON.parse(result.stdout);
+    } catch {
+      // fall through to the local file
+    }
+  }
+  if (existsSync(MANIFEST_PATH)) {
+    try {
+      return JSON.parse(readFileSync(MANIFEST_PATH, "utf8"));
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Pure regen-permission rule (unit-tested in src/skill-manifest.test.js).
+ * Content that differs from the baseline while keeping the baseline's
+ * version is refused: once a version's content is on origin/main, changing
+ * content under that version always requires a bump. A differing version
+ * (the in-flight bump case, iterated freely within one branch) and a
+ * missing baseline (true first generation) are allowed. There is
+ * deliberately NO force escape hatch: an override flag would let
+ * unversioned content changes reach npm and the public skills repo.
+ */
+export function assertRegenAllowed({ baseline, next }) {
+  if (!baseline) return;
+  if (baseline.contentHash === next.contentHash) return;
+  if (baseline.version !== next.version) return;
+  throw new Error(
+    `skill content changed but metadata.version is still ${next.version}, whose content is already fixed by the baseline manifest (origin/main) — bump the version in SKILL.md, then rerun npm run skill:manifest.`
+  );
+}
+
+function main() {
+  const manifest = buildSkillManifest();
+  try {
+    assertRegenAllowed({ baseline: baselineSkillManifest(), next: manifest });
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+  writeFileSync(MANIFEST_PATH, `${JSON.stringify(manifest, null, 2)}\n`);
+  process.stdout.write(
+    `Wrote ${path.relative(packageDir, MANIFEST_PATH)}: version ${manifest.version}, ${manifest.files} files, contentHash ${manifest.contentHash}\n`
+  );
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main();
+}

package/skill/gmc-analysis/CHANGELOG.md

@@ -1,5 +1,43 @@
 # gmc-analysis skill changelog
 
+## 0.5.0 - 2026-07-13
+
+- New "Saved Game Lists" section in SKILL.md, plus recipe R5 in
+  `references/recipes.md` (NAK-155/NAK-178/NAK-189): documents Game Lists as
+  reusable, workspace-scoped cohort inputs — `gmc lists ...` (CLI) or the 7
+  MCP tools (`list_game_lists`, `get_game_list`, `create_game_list`,
+  `update_game_list`, `add_game_list_items`, `remove_game_list_item`,
+  `delete_game_list`), all 0-credit; passing a filter-kind list's id as
+  `game_list_id`/`--list <id>` to `list_games`, `market_aggregate`,
+  `cohort_review_categories`, or `cohort_evidence` instead of re-sending an
+  inline filter; reading `game_list.definition_hash` to detect a changed
+  stored definition between calls; the composite-list tool restriction
+  (`COMPOSITE_LIST_UNSUPPORTED_FOR_TOOL` on `market_aggregate`/
+  `cohort_review_categories`), the manual-list restriction
+  (`GAME_LIST_KIND_UNSUPPORTED`), and `delete_game_list`'s MCP confirm-by-
+  exact-name two-call contract.
+- `references/charts.md` retroactive documentation (NAK-190): this
+  changelog entry catches up two content changes that shipped without a
+  skill version bump because nothing enforced one at the time (see the new
+  content-hash manifest guard below, added in this same release, to prevent
+  a repeat):
+  - PR #18 (NAK-139..143): new chart types beyond horizontal bar (lollipop,
+    grouped column, stacked column, dumbbell, scatter, quadrant with
+    computed threshold lines, donut, hero-number card); Steam capsule rows
+    for per-game bar charts; wide (16:9, 1200x675) and square (1:1,
+    1080x1080) export geometry replacing the earlier vertical (4:5) option.
+  - PR #43 (NAK-166/NAK-142): direct-label placement rules (values at bar/
+    line ends instead of legends, corner labels on quadrant charts) and the
+    embedded brand typography stack (Inter / JetBrains Mono / Quicksand)
+    used across card title, footer, and source-label text.
+- Added `packages/gmc-cli/scripts/gen-skill-manifest.mjs` and
+  `packages/gmc-cli/src/skill-manifest.test.js` (NAK-190): a content-hash
+  manifest (`skill/gmc-analysis.manifest.json`, outside the synced skill
+  directory) that fails `npm run test:cli` whenever `skill/gmc-analysis/**`
+  content changes without a matching `metadata.version` bump and manifest
+  regeneration (`npm run skill:manifest`) — the gap that let the two chart
+  entries above ship unversioned.
+
 ## 0.4.0 - 2026-07-09
 
 - Added `references/validity.md` (NAK-82): statistical-validity checklist

package/skill/gmc-analysis/SKILL.md

@@ -8,7 +8,7 @@ description: >-
   or campaigns that GMC can answer — including turning results into
   publish-ready branded chart cards.
 metadata:
-  version: 0.4.0
+  version: 0.5.0
 ---
 
 # GMC Analysis
@@ -96,6 +96,50 @@ Search commands are optimized for row retrieval. Do not expect
 unless you explicitly pass `--include-total`; for count-only questions use
 `gmc games count` instead.
 
+## Saved Game Lists (reusable cohort definitions)
+
+A Game List is a workspace-scoped, reusable cohort input — persist a filter
+(or an explicit appid set) once instead of re-sending a large inline filter
+on every call.
+
+- Manage lists via `gmc lists ...` (`list`, `create`, `show`, `games`, `add`,
+  `remove`, `delete`) or the MCP tools `list_game_lists` / `get_game_list` /
+  `create_game_list` / `update_game_list` / `add_game_list_items` /
+  `remove_game_list_item` / `delete_game_list`. All are 0-credit and scoped
+  to the caller's own workspace.
+- Two kinds: `manual` (explicit appid membership) and `filter` (a stored
+  `GameFilter`, re-evaluated live against current data on every read). The
+  MCP `game_list_id` input accepts `filter`-kind lists only; the CLI
+  `--list <id>` flag resolves membership server-side and accepts BOTH kinds.
+- Pass a filter-kind list's `id` as `game_list_id` to `list_games`,
+  `market_aggregate`, `cohort_review_categories`, or `cohort_evidence`
+  instead of re-sending the inline filter — mutually exclusive with
+  `filter` (`INVALID_INPUT` if both or neither are given). CLI equivalent:
+  `--list <id>` on `gmc reviews patterns`, `gmc marketing patterns`, and
+  `gmc cohort ...` (cohort-evidence-shaped commands only — `gmc games
+  count`/`gmc games aggregate` have no `--list` flag; use `market_aggregate`
+  with `game_list_id` over MCP for that).
+- The response's `game_list.definition_hash` (a SHA-256 over `{kind,
+  filter, sort}`) tells you whether the stored definition changed between
+  calls — diff hashes across calls instead of re-diffing the filter
+  yourself.
+
+Sharp edges:
+
+- **Composite (union) lists** work only with `list_games`/`cohort_evidence`;
+  `market_aggregate`/`cohort_review_categories` reject them with
+  `COMPOSITE_LIST_UNSUPPORTED_FOR_TOOL` (those two are single aggregate
+  calls that cannot be bound to an explicit appid population).
+- **Manual lists cannot be used as `game_list_id`** (MCP only) — a
+  `kind:"manual"` list fails `GAME_LIST_KIND_UNSUPPORTED` there. Use the
+  CLI `--list <id>` flag (which accepts manual lists), or read membership
+  directly (`gmc lists games <id>` / `get_game_list`).
+- `delete_game_list` is destructive and, over MCP, uses a confirm-by-
+  exact-name two-call contract: a call without `confirm` fails
+  `CONFIRMATION_REQUIRED`, naming the list; only pass `confirm` set to that
+  exact name after the user has explicitly asked to delete it — never
+  guess or pre-fill it speculatively.
+
 ## Hard rules
 
 - **Missing data is not absent sentiment.** Report `cohort.usableGames`,

package/skill/gmc-analysis/references/charts.md

@@ -34,25 +34,68 @@ violates the non-negotiables below must not carry GMC attribution.
    entirely. If one must appear, add a second, visually separate footnote
    line: `External estimate: <source> — not GMC data`.
 7. **Opaque background** (`#fafaf7` page, `#ffffff` card). Never export
-   transparent PNGs. Recommended export: X 1200x675, LinkedIn 1200x627,
-   or the natural 720px card width at 2x.
+   transparent PNGs. Export geometry: 16:9 1200x675 (X default) or 1:1
+   1080x1080 (X-safe; donut/kpi/quadrant read best). Vertical (4:5) cards
+   are not produced. Default to 16:9 when unsure.
 
 ## Picking the chart type from gmc output shapes
 
 | Output | Shape | Chart |
 |---|---|---|
 | `gmc games aggregate --group-by <dim>` / MCP `market_aggregate` | 6+ groups, rank matters | Horizontal bar, sorted desc |
+| same | 6+ groups, rank matters, compact point emphasis | Lollipop (bar_h variant) |
 | same | 2-5 groups | Vertical column |
+| same | 2-4 series × categories, e.g. release count by year × price band | Grouped column |
+| same | 2-4 part-of-whole series across categories | Stacked column |
+| same | before/after pairs per category, exactly 2 series | Dumbbell |
 | same, time buckets (release windows, months) | series over time | Line (single/few series) or column |
 | MCP `market_aggregate` with `segment_filter` | segment vs base | Two big numbers + ratio, or grouped bar |
 | `gmc reviews patterns` / MCP `cohort_evidence` / clustered `negativeThemes` | theme -> game counts | Horizontal bar; caption carries `x of N usable games` |
 | MCP `coverage_check` / `gmc games count --group-by coverage` | composition, 2-4 segments | Donut with absolute counts printed, or one 100% stacked bar |
+| any tool output with x/y metric pairs per point | two metrics correlation | Scatter |
+| any tool output with x/y metric pairs for positioning | scatter + median threshold lines + 4 descriptive corner labels; thresholds are computed from plotted values, never chosen | Quadrant |
 | single KPI (one count, one median, one share) | one number | Hero number card (no chart canvas) |
 
 Rules of thumb: when unsure, use a horizontal bar. One message per card.
 Never: 3D, dual axes, cropped bar baselines, pie with 5+ slices, line
 charts for non-time data.
 
+## Steam capsules for game rows
+
+When bar rows are individual game titles, show the Steam capsule
+(`https://shared.akamai.steamstatic.com/store_item_assets/steam/apps/{appid}/capsule_231x87.jpg`,
+231x87) left of the row label. Preload images before render; skip rows whose
+image failed so the text-only fallback keeps the layout. Scatter/quadrant
+points get the same treatment as a thumbnail overlay per the visual guide's
+thumbnail-overlay pattern: a white, 1px-framed capsule anchored near the
+point with a dashed leader line back to it, instead of a row-left capsule.
+
+```js
+const rows = [{ label: '{{GAME TITLE}}', appid: 0 }];
+const capsuleImages = await Promise.all(rows.map(({ appid }) => new Promise((resolve) => {
+  if (!appid) return resolve(null);
+  const img = new Image();
+  img.onload = () => resolve(img);
+  img.onerror = () => resolve(null);
+  img.src = `https://shared.akamai.steamstatic.com/store_item_assets/steam/apps/${appid}/capsule_231x87.jpg`;
+})));
+
+const steamCapsules = {
+  id: 'steamCapsules',
+  afterDraw(chart) {
+    const yScale = chart.scales.y;
+    if (!yScale) return;
+    const { ctx } = chart;
+    yScale.ticks.forEach((_, i) => {
+      const img = capsuleImages[i];
+      if (!img) return;
+      const y = yScale.getPixelForTick(i) - 14;
+      ctx.drawImage(img, yScale.left - 66, y, 54, 20);
+    });
+  }
+};
+```
+
 ## Color
 
 Neutrals (fixed): page `#fafaf7`, card `#ffffff`, ink `#1a1d20`, muted
@@ -79,7 +122,7 @@ network access for fonts, Chart.js CDN, and the brand lockup.
 <head>
 <meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
-<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@400;500&family=Instrument+Serif&display=swap" rel="stylesheet">
+<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@400;500&family=Quicksand:wght@700&display=swap" rel="stylesheet">
 <script src="https://cdn.jsdelivr.net/npm/chart.js@4"></script>
 <style>
   :root {
@@ -88,7 +131,7 @@ network access for fonts, Chart.js CDN, and the brand lockup.
     --rule: #e8e5de; --accent: #ec7336;
     --sans: 'Inter', system-ui, sans-serif;
     --mono: 'JetBrains Mono', ui-monospace, monospace;
-    --serif: 'Instrument Serif', Georgia, serif;
+    --title: 'Quicksand', 'Inter', system-ui, sans-serif;
   }
   * { margin: 0; padding: 0; box-sizing: border-box; }
   body { background: var(--bg); font-family: var(--sans); color: var(--ink);
@@ -101,8 +144,8 @@ network access for fonts, Chart.js CDN, and the brand lockup.
               color: var(--accent); max-width: 76%; }
   .card-cat { font-family: var(--mono); font-size: 10px; letter-spacing: 0.12em;
               text-transform: uppercase; color: var(--ink-faint); white-space: nowrap; }
-  .card-title { padding: 26px 20px 8px; font-family: var(--serif);
-                font-size: 34px; line-height: 1.12; font-weight: 400; }
+  .card-title { padding: 26px 20px 8px; font-family: var(--title);
+                font-size: 34px; line-height: 1.12; font-weight: 700; }
   .chart-wrap { position: relative; margin: 18px 20px 8px;
                 min-height: 470px; height: 470px; }
   .card-foot { display: flex; justify-content: space-between; align-items: center;
@@ -208,7 +251,8 @@ Variants:
 
 Japanese edition: add `&family=Noto+Sans+JP:wght@400;500;600` to the fonts
 URL, append `'Noto Sans JP'` to `--sans`, set `<html lang="ja">`, and use
-`GMCデータベース` as the source label. Steam tags in JA charts:
+`GMCデータベース` as the source label. Add `&family=Noto+Serif+JP:wght@400&`
+to the fonts URL so JA titles render serif. Steam tags in JA charts:
 `English Tag(日本語タグ名)` on first appearance.
 
 ## Capture

package/skill/gmc-analysis/references/recipes.md

@@ -95,6 +95,33 @@ gives the well-rated share. Divide by the unconditional bucket counts.
 Never read unconditional rating aggregates in low-traction buckets
 (pitfall P5).
 
+## R5. Repeatable cohort via a saved Game List
+
+When a cohort filter will be reused across a session or a recurring
+digest, persist it once instead of re-sending the inline filter on every
+call.
+
+```bash
+# 1. Create the filter-kind list once
+gmc lists create --name "<label>" --kind filter \
+  --filter '{"tags":["<tag>"],"reviewsMin":<n>}' --json   # -> data.id
+
+# 2. Reference it on every follow-up call instead of the inline filter
+gmc reviews patterns --source steam --list <id> --json
+gmc cohort brief --source steam --list <id> --json
+```
+
+Over MCP, `create_game_list` once, then pass its `id` as `game_list_id` to
+`list_games` / `market_aggregate` / `cohort_review_categories` /
+`cohort_evidence` on every follow-up call. Check `game_list.definition_hash`
+on each response — a changed hash means the stored DEFINITION was edited;
+re-state the cohort definition before comparing numbers. A stable hash does
+not freeze the population: filter lists re-evaluate live, so denominators
+can still move between calls. Composite (union) lists only work with `list_games`/
+`cohort_evidence` (this recipe's map-reduce sibling, R2); manual lists are
+not a `game_list_id` input over MCP (the CLI `--list <id>` flag does accept
+them) — read their membership with `gmc lists games <id>` / `get_game_list`.
+
 ## Output contract for every analysis
 
 Always include in your final answer: the cohort definition and size, how many

package/skill/gmc-analysis.manifest.json

@@ -0,0 +1,5 @@
+{
+  "version": "0.5.0",
+  "contentHash": "0a8b585ed7b76dab31fb468b7ff58e97a4a31a24fc00b595118aad31dadfeb60",
+  "files": 7
+}

package/src/constants.js

@@ -7,7 +7,7 @@ export const EXIT_CONFIG = 3;
 export const EXIT_API = 4;
 
 export const CLI_PACKAGE_NAME = "@witchpot/gmc";
-export const CLI_VERSION = "0.4.0";
+export const CLI_VERSION = "0.5.0";
 
 export const DEFAULT_API_BASE_URL = "https://gamemarketcopilot.com";
 export const DEFAULT_CONFIG_PATH = path.join(homedir(), ".config", "gmc", "config.json");

package/src/skill-manifest.test.js

@@ -0,0 +1,62 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test from "node:test";
+
+import {
+  MANIFEST_PATH,
+  assertRegenAllowed,
+  computeSkillContentHash,
+  readSkillManifestVersion
+} from "../scripts/gen-skill-manifest.mjs";
+
+const FAILURE_MESSAGE =
+  "skill content changed: bump metadata.version in SKILL.md, run npm run skill:manifest (in packages/gmc-cli), and re-sync the gmc-agent-skills distribution repo (node scripts/sync-from-cli.mjs there)";
+
+function readCommittedManifest() {
+  return JSON.parse(readFileSync(MANIFEST_PATH, "utf8"));
+}
+
+test("committed skill manifest content hash matches the packaged skill content", () => {
+  const manifest = readCommittedManifest();
+  const { contentHash } = computeSkillContentHash();
+
+  assert.equal(contentHash, manifest.contentHash, FAILURE_MESSAGE);
+});
+
+test("committed skill manifest version matches SKILL.md metadata.version", () => {
+  const manifest = readCommittedManifest();
+  const skillVersion = readSkillManifestVersion();
+
+  assert.equal(manifest.version, skillVersion, FAILURE_MESSAGE);
+});
+
+test("regen rule: content change under the baseline's version is refused", () => {
+  assert.throws(
+    () =>
+      assertRegenAllowed({
+        baseline: { version: "0.5.0", contentHash: "aaa" },
+        next: { version: "0.5.0", contentHash: "bbb" }
+      }),
+    /bump the version in SKILL\.md/
+  );
+});
+
+test("regen rule: allowed on a bump, on unchanged content, and on first generation", () => {
+  // A bump (in-flight iteration keeps hitting this branch: baseline stays
+  // at origin/main's version until the bump merges).
+  assert.doesNotThrow(() =>
+    assertRegenAllowed({
+      baseline: { version: "0.4.0", contentHash: "aaa" },
+      next: { version: "0.5.0", contentHash: "bbb" }
+    })
+  );
+  // Idempotent rerun.
+  assert.doesNotThrow(() =>
+    assertRegenAllowed({
+      baseline: { version: "0.5.0", contentHash: "aaa" },
+      next: { version: "0.5.0", contentHash: "aaa" }
+    })
+  );
+  // True first generation (no committed baseline anywhere).
+  assert.doesNotThrow(() => assertRegenAllowed({ baseline: undefined, next: { version: "0.5.0", contentHash: "aaa" } }));
+});