@celilo/cli 0.7.1 → 0.8.0

package/src/cli/index.ts

@@ -48,6 +48,7 @@ import { handleMachineRemove } from './commands/machine-remove';
 import { handleMachineStatus } from './commands/machine-status';
 import { moduleAudit } from './commands/module-audit';
 import { handleModuleBuild } from './commands/module-build';
+import { handleModuleChangeset } from './commands/module-changeset';
 import { handleModuleCheck } from './commands/module-check';
 import { handleModuleConfigGet, handleModuleConfigSet } from './commands/module-config';
 import { handleModuleDeploy } from './commands/module-deploy';
@@ -66,9 +67,8 @@ import { handleModuleTypesCheck, handleModuleTypesGenerate } from './commands/mo
 import { handleModuleUpdate } from './commands/module-update';
 import { handleModuleUpgrade } from './commands/module-upgrade';
 import { moduleVerify } from './commands/module-verify';
+import { handleModuleVersion } from './commands/module-version';
 import { handlePackage } from './commands/package';
-import { handleProxmoxInstanceList } from './commands/proxmox-instance-list';
-import { handleProxmoxInstanceResize } from './commands/proxmox-instance-resize';
 import { handleProxmoxNodeList } from './commands/proxmox-node-list';
 import { main as runPublish } from './commands/publish';
 import { handleSecretList } from './commands/secret-list';
@@ -1272,6 +1272,10 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
         return handleModuleUpdate(parsed.args, parsed.flags);
       case 'upgrade':
         return handleModuleUpgrade(parsed.args, parsed.flags);
+      case 'version':
+        return handleModuleVersion(parsed.args, parsed.flags);
+      case 'changeset':
+        return handleModuleChangeset(parsed.args, parsed.flags);
       case 'audit':
         return moduleAudit(parsed.args);
       case 'verify':
@@ -1818,19 +1822,6 @@ export async function runCli(argv: string[]): Promise<CommandResult> {
         error: 'Proxmox node action required (list)\n\nRun "celilo proxmox --help" for usage',
       };
     }
-    if (parsed.subcommand === 'vm' || parsed.subcommand === 'ct') {
-      const action = parsed.args[0];
-      if (action === 'list') {
-        return handleProxmoxInstanceList(parsed.subcommand, parsed.args.slice(1));
-      }
-      if (action === 'resize') {
-        return handleProxmoxInstanceResize(parsed.subcommand, parsed.args.slice(1), parsed.flags);
-      }
-      return {
-        success: false,
-        error: `Proxmox ${parsed.subcommand} action required (list, resize)\n\nRun "celilo proxmox --help" for usage`,
-      };
-    }
     return {
       success: false,
       error: `Unknown proxmox subcommand: ${parsed.subcommand}\n\nRun "celilo proxmox --help" for usage`,

package/src/db/schema.ts

@@ -392,17 +392,6 @@ export const moduleSystems = sqliteTable(
     serviceId: text('service_id').references(() => containerServices.id),
     /** Proxmox VMID — set only for proxmox containers. */
     vmid: integer('vmid'),
-    // Canonical deployed SIZE of this system (ISS-0150). For celilo-provisioned
-    // VM/LXC instances only (null for machine-pool systems celilo doesn't size).
-    // Seeded from the module's `requires.system` at first provision, then owned
-    // by `celilo proxmox … resize` — `requires.system` is only the minimum floor,
-    // never the live size. See CLAUDE.md "requires.system is the MINIMUM".
-    /** vCPU cores. */
-    cpu: integer('cpu'),
-    /** RAM in MB. */
-    memory: integer('memory'),
-    /** Root disk in GB. */
-    disk: integer('disk'),
     createdAt: integer('created_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
     updatedAt: integer('updated_at', { mode: 'timestamp' }).notNull().default(sql`(unixepoch())`),
   },

package/src/manifest/schema.ts

@@ -443,6 +443,30 @@ export const ModuleManifestSchema = z
     version: z.string().regex(/^\d+\.\d+\.\d+$/, 'Version must be semantic version (e.g., 1.0.0)'),
     description: z.string().optional(),
 
+    /**
+     * How `manifest.yml#version` (the PAYLOAD version) is determined — see
+     * v2/MODULE_VERSIONING.md / ISS-0151. The capability *contract* version
+     * lives in `provides.capabilities[].version` and is unrelated to this.
+     *
+     * - `changeset` — first-party apps/content (lunacycle): the version is
+     *   authored via `.changeset/*.md` keyed by the module id; `celilo module
+     *   version` stamps it here. Ordered by the `+N` revision; semver is a
+     *   blast-radius/posture signal, not a contract.
+     * - `pin` — wrapper modules (caddy, forgejo): `resolver` returns the
+     *   upstream version actually installed; `module check` fails on drift.
+     * - `recipe` — payload-less modules (iptables): no software version; `+N`
+     *   orders. The default when this block is absent, preserving today's
+     *   behaviour for unmigrated modules.
+     */
+    version_source: z
+      .object({
+        kind: z.enum(['pin', 'changeset', 'recipe']),
+        /** For `kind: pin`: path (module-relative) to a script printing the upstream version. */
+        resolver: z.string().optional(),
+      })
+      .strict()
+      .optional(),
+
     requires: z
       .object({
         capabilities: z.array(CapabilityRequirementSchema).default([]),

package/src/module/versioning/changeset-version.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it } from 'bun:test';
+import {
+  type BumpType,
+  type ModuleVersionPlan,
+  applyBump,
+  maxBump,
+  parseChangeset,
+  planModuleVersion,
+  renderChangelogSection,
+} from './changeset-version';
+
+describe('parseChangeset', () => {
+  it('parses quoted id + bump and the summary body', () => {
+    const r = parseChangeset('---\n"lunacycle": minor\n---\n\nAdded a thing.\n');
+    expect(r.bumps).toEqual({ lunacycle: 'minor' });
+    expect(r.summary).toBe('Added a thing.');
+  });
+
+  it('parses unquoted ids and multiple modules', () => {
+    const r = parseChangeset('---\nlunacycle: patch\nnigredo: major\n---\nfix\n');
+    expect(r.bumps).toEqual({ lunacycle: 'patch', nigredo: 'major' });
+  });
+
+  it('throws on a missing frontmatter fence', () => {
+    expect(() => parseChangeset('just a summary, no frontmatter')).toThrow(/frontmatter/);
+  });
+
+  it('throws on an invalid bump keyword', () => {
+    expect(() => parseChangeset('---\nlunacycle: huge\n---\n')).toThrow(/major\|minor\|patch/);
+  });
+
+  it('throws on a frontmatter line without a colon', () => {
+    expect(() => parseChangeset('---\nlunacycle minor\n---\n')).toThrow(/not "id: bump"/);
+  });
+});
+
+describe('maxBump', () => {
+  it('ranks major > minor > patch', () => {
+    expect(maxBump(['patch', 'major', 'minor'])).toBe('major');
+    expect(maxBump(['patch', 'minor'])).toBe('minor');
+    expect(maxBump(['patch'])).toBe('patch');
+  });
+  it('returns null for an empty list', () => {
+    expect(maxBump([])).toBeNull();
+  });
+});
+
+describe('applyBump', () => {
+  it('bumps each level and zeroes lower segments', () => {
+    expect(applyBump('1.2.3', 'major')).toBe('2.0.0');
+    expect(applyBump('1.2.3', 'minor')).toBe('1.3.0');
+    expect(applyBump('1.2.3', 'patch')).toBe('1.2.4');
+  });
+  it('throws on a non x.y.z version', () => {
+    expect(() => applyBump('1.2', 'patch')).toThrow(/x\.y\.z/);
+    expect(() => applyBump('1.0.0+4', 'patch')).toThrow(/x\.y\.z/);
+  });
+});
+
+describe('planModuleVersion', () => {
+  const cs = (id: string, bump: BumpType, summary = '') =>
+    parseChangeset(`---\n"${id}": ${bump}\n---\n${summary}\n`);
+
+  it('returns null when no changeset targets the module', () => {
+    expect(planModuleVersion('1.0.0', 'lunacycle', [])).toBeNull();
+    expect(planModuleVersion('1.0.0', 'lunacycle', [cs('nigredo', 'minor')])).toBeNull();
+  });
+
+  it('takes the max bump across relevant changesets', () => {
+    const plan = planModuleVersion('1.2.3', 'lunacycle', [
+      cs('lunacycle', 'patch', 'a'),
+      cs('lunacycle', 'minor', 'b'),
+      cs('nigredo', 'major', 'unrelated'),
+    ]);
+    expect(plan).not.toBeNull();
+    expect(plan?.bump).toBe('minor');
+    expect(plan?.next).toBe('1.3.0');
+    expect(plan?.entries).toEqual(['a', 'b']);
+  });
+
+  it('omits empty summaries from entries', () => {
+    const plan = planModuleVersion('1.0.0', 'lunacycle', [
+      cs('lunacycle', 'patch', ''),
+      cs('lunacycle', 'patch', 'real'),
+    ]);
+    expect(plan?.entries).toEqual(['real']);
+  });
+});
+
+describe('renderChangelogSection', () => {
+  it('renders a newest-on-top section with the bump heading', () => {
+    const plan = planModuleVersion('1.0.0', 'lunacycle', [
+      parseChangeset('---\nlunacycle: minor\n---\nAdded tasks view.\n'),
+    ]);
+    expect(plan).not.toBeNull();
+    const md = renderChangelogSection(plan as ModuleVersionPlan);
+    expect(md).toContain('## 1.1.0');
+    expect(md).toContain('### Minor Changes');
+    expect(md).toContain('- Added tasks view.');
+  });
+
+  it('falls back to a generic bullet when there are no summaries', () => {
+    const plan = planModuleVersion('1.0.0', 'lunacycle', [
+      parseChangeset('---\nlunacycle: patch\n---\n'),
+    ]);
+    expect(renderChangelogSection(plan as ModuleVersionPlan)).toContain('- Version bump.');
+  });
+});

package/src/module/versioning/changeset-version.ts

@@ -0,0 +1,139 @@
+/**
+ * Changeset-driven module versioning (ISS-0151 / v2/MODULE_VERSIONING.md).
+ *
+ * For `version_source: { kind: changeset }` modules, the payload version is
+ * authored via `.changeset/*.md` files — the same on-disk format the changesets
+ * CLI uses, but keyed by the MODULE id (Option A) rather than an npm package, so
+ * a celilo module needs no package.json. `celilo module version` reads those
+ * files, computes the next `manifest.yml#version`, and writes a CHANGELOG.
+ *
+ * This file is the pure core: parsing + semver math, no filesystem. The command
+ * (module-version.ts) does the I/O.
+ */
+
+export type BumpType = 'major' | 'minor' | 'patch';
+
+const BUMP_RANK: Record<BumpType, number> = { patch: 1, minor: 2, major: 3 };
+
+export function isBumpType(s: string): s is BumpType {
+  return s === 'major' || s === 'minor' || s === 'patch';
+}
+
+export interface ParsedChangeset {
+  /** module id → declared bump, from the `---` frontmatter. */
+  bumps: Record<string, BumpType>;
+  /** the markdown body after the frontmatter, trimmed. */
+  summary: string;
+}
+
+/**
+ * Parse one changeset `.md`: a YAML-ish frontmatter block fenced by `---`
+ * mapping `"<module-id>": <bump>` (quotes optional), followed by a prose body.
+ *
+ * Throws on a malformed frontmatter fence or an invalid bump keyword — a
+ * changeset that can't be understood must fail loudly, not silently no-op.
+ */
+export function parseChangeset(content: string): ParsedChangeset {
+  const normalized = content.replace(/\r\n/g, '\n');
+  const match = normalized.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) {
+    throw new Error('changeset has no `---` frontmatter block');
+  }
+  const [, frontmatter, body] = match;
+
+  const bumps: Record<string, BumpType> = {};
+  for (const rawLine of frontmatter.split('\n')) {
+    const line = rawLine.trim();
+    if (!line) continue;
+    const sep = line.indexOf(':');
+    if (sep === -1) {
+      throw new Error(`changeset frontmatter line is not "id: bump": ${line}`);
+    }
+    const id = line
+      .slice(0, sep)
+      .trim()
+      .replace(/^['"]|['"]$/g, '');
+    const bump = line
+      .slice(sep + 1)
+      .trim()
+      .replace(/^['"]|['"]$/g, '');
+    if (!id) throw new Error(`changeset frontmatter has an empty module id: ${line}`);
+    if (!isBumpType(bump)) {
+      throw new Error(`changeset bump for "${id}" must be major|minor|patch, got "${bump}"`);
+    }
+    bumps[id] = bump;
+  }
+
+  return { bumps, summary: body.trim() };
+}
+
+/** Highest-ranked bump in the list, or null if empty. */
+export function maxBump(bumps: BumpType[]): BumpType | null {
+  let best: BumpType | null = null;
+  for (const b of bumps) {
+    if (best === null || BUMP_RANK[b] > BUMP_RANK[best]) best = b;
+  }
+  return best;
+}
+
+/** Apply a semver bump to an `x.y.z` string. Throws if `version` isn't `x.y.z`. */
+export function applyBump(version: string, bump: BumpType): string {
+  const m = version.match(/^(\d+)\.(\d+)\.(\d+)$/);
+  if (!m) throw new Error(`version must be x.y.z, got "${version}"`);
+  const [major, minor, patch] = [Number(m[1]), Number(m[2]), Number(m[3])];
+  switch (bump) {
+    case 'major':
+      return `${major + 1}.0.0`;
+    case 'minor':
+      return `${major}.${minor + 1}.0`;
+    case 'patch':
+      return `${major}.${minor}.${patch + 1}`;
+  }
+}
+
+export interface ModuleVersionPlan {
+  current: string;
+  next: string;
+  bump: BumpType;
+  /** summaries of the changesets that target this module, for the CHANGELOG. */
+  entries: string[];
+}
+
+/**
+ * Compute the next version for `moduleId` from the parsed changesets. Returns
+ * null when no changeset targets this module — "nothing to version" is a clean
+ * no-op, not an error (e.g. a docs-only PR added a changeset for another module,
+ * or none at all).
+ */
+export function planModuleVersion(
+  current: string,
+  moduleId: string,
+  changesets: ParsedChangeset[],
+): ModuleVersionPlan | null {
+  const relevant = changesets.filter((c) => moduleId in c.bumps);
+  if (relevant.length === 0) return null;
+
+  const bump = maxBump(relevant.map((c) => c.bumps[moduleId]));
+  // relevant is non-empty, so maxBump is non-null.
+  if (bump === null) return null;
+
+  const entries = relevant.map((c) => c.summary).filter((s) => s.length > 0);
+  return { current, next: applyBump(current, bump), bump, entries };
+}
+
+/**
+ * Render a CHANGELOG section for a computed plan (newest-on-top convention).
+ * The command prepends this below the file-level `# <module-id>` header.
+ */
+export function renderChangelogSection(plan: ModuleVersionPlan): string {
+  const heading: Record<BumpType, string> = {
+    major: 'Major Changes',
+    minor: 'Minor Changes',
+    patch: 'Patch Changes',
+  };
+  const lines = [`## ${plan.next}`, '', `### ${heading[plan.bump]}`, ''];
+  const bullets = plan.entries.length > 0 ? plan.entries : ['Version bump.'];
+  for (const e of bullets) lines.push(`- ${e.replace(/\n+/g, ' ').trim()}`);
+  lines.push('');
+  return lines.join('\n');
+}

package/src/services/deployed-systems.test.ts

@@ -1,7 +1,6 @@
 import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
 import { existsSync } from 'node:fs';
 import { rm } from 'node:fs/promises';
-import { and, eq } from 'drizzle-orm';
 import { type DbClient, createDbClient } from '../db/client';
 import {
   containerServices,
@@ -11,7 +10,7 @@ import {
   moduleSystems,
   modules,
 } from '../db/schema';
-import { backfillModuleSystems, getModuleSystems, upsertDeployedSystem } from './deployed-systems';
+import { backfillModuleSystems, getModuleSystems } from './deployed-systems';
 
 const TEST_DB_PATH = './test-deployed-systems.db';
 
@@ -234,74 +233,3 @@ describe('backfillModuleSystems', () => {
     expect(getModuleSystems('namecheap', db)).toHaveLength(0);
   });
 });
-
-/**
- * Canonical instance sizing (ISS-0150): sizing is seeded onto module_systems
- * once at first provision and then OWNED by `celilo proxmox … resize` — a routine
- * re-deploy must never reset a resized instance back to its manifest minimum.
- */
-describe('upsertDeployedSystem sizing — seed-once (ISS-0150)', () => {
-  let db: DbClient;
-
-  beforeEach(() => {
-    db = createDbClient({ path: TEST_DB_PATH });
-    db.insert(modules)
-      .values({
-        id: 'm1',
-        name: 'm1',
-        version: '1.0.0',
-        manifestData: {},
-        sourcePath: '/tmp/m1',
-        state: 'VERIFIED',
-      })
-      .run();
-  });
-
-  afterEach(async () => {
-    db.$client.close();
-    for (const suffix of ['', '-shm', '-wal']) {
-      const p = `${TEST_DB_PATH}${suffix}`;
-      if (existsSync(p)) await rm(p);
-    }
-  });
-
-  const sizeArgs = (memory: number) => ({
-    name: 'main',
-    hostname: 'h',
-    ipv4Address: '10.0.0.5/24',
-    zone: 'app' as const,
-    infraType: 'container_service' as const,
-    vmid: 200,
-    cpu: 4,
-    memory,
-    disk: 80,
-  });
-
-  const row = () =>
-    db
-      .select()
-      .from(moduleSystems)
-      .where(and(eq(moduleSystems.moduleId, 'm1'), eq(moduleSystems.name, 'main')))
-      .get();
-
-  test('seeds sizing on first insert', () => {
-    upsertDeployedSystem(db, 'm1', sizeArgs(8192));
-    const r = row();
-    expect(r?.cpu).toBe(4);
-    expect(r?.memory).toBe(8192);
-    expect(r?.disk).toBe(80);
-  });
-
-  test('a re-deploy does NOT reset a resized instance to the manifest minimum', () => {
-    upsertDeployedSystem(db, 'm1', sizeArgs(8192)); // first provision: seed 8 GB
-    // Simulate `celilo proxmox vm resize` bumping the canonical size to 16 GB.
-    db.update(moduleSystems)
-      .set({ memory: 16384 })
-      .where(and(eq(moduleSystems.moduleId, 'm1'), eq(moduleSystems.name, 'main')))
-      .run();
-    // Re-deploy passes the manifest minimum (8 GB) again — must be ignored.
-    upsertDeployedSystem(db, 'm1', sizeArgs(8192));
-    expect(row()?.memory).toBe(16384);
-    expect(row()?.cpu).toBe(4);
-  });
-});

package/src/services/deployed-systems.ts

@@ -52,52 +52,6 @@ export function getModuleSystems(moduleId: string, db: DbClient): DeployedSystem
   return rows.map(rowToSystem).sort((a, b) => a.name.localeCompare(b.name));
 }
 
-/**
- * A celilo-provisioned instance with its canonical size (ISS-0150). CLI-internal
- * shape (NOT the `DeployedSystem` capability type) for the `celilo proxmox
- * vm/ct …` surface, which needs the sizing columns the capability type omits.
- */
-export interface ProvisionedSystem {
-  moduleId: string;
-  name: string;
-  hostname: string;
-  ipv4Address: string;
-  zone: NetworkZone;
-  serviceId: string | null;
-  vmid: number | null;
-  /** Canonical desired size (null until seeded / for non-Proxmox). */
-  cpu: number | null;
-  memory: number | null;
-  disk: number | null;
-}
-
-/**
- * Every celilo-provisioned (container_service) system with a Proxmox vmid, across
- * all modules, including its canonical sizing — the read model behind
- * `celilo proxmox vm/ct list|show`. Ordered by vmid for stable output.
- */
-export function getProvisionedSystems(db: DbClient): ProvisionedSystem[] {
-  return db
-    .select()
-    .from(moduleSystems)
-    .where(eq(moduleSystems.infraType, 'container_service'))
-    .all()
-    .filter((r) => r.vmid != null)
-    .map((r) => ({
-      moduleId: r.moduleId,
-      name: r.name,
-      hostname: r.hostname,
-      ipv4Address: r.ipv4Address,
-      zone: r.zone,
-      serviceId: r.serviceId,
-      vmid: r.vmid,
-      cpu: r.cpu,
-      memory: r.memory,
-      disk: r.disk,
-    }))
-    .sort((a, b) => (a.vmid ?? 0) - (b.vmid ?? 0));
-}
-
 /**
  * All container_service systems (Proxmox LXCs, droplets, …) whose zone is in
  * `zones`, across every module — the LXC complement to machine-pool's
@@ -139,15 +93,6 @@ export interface DeployedSystemInput {
   machineId?: string | null;
   serviceId?: string | null;
   vmid?: number | null;
-  /**
-   * Canonical deployed size (ISS-0150), seeded from the module's
-   * `requires.system` at first provision. Seed-once: written on INSERT only and
-   * preserved across re-deploys (omitted from the conflict update), so a later
-   * `celilo proxmox … resize` is not reset back to the manifest minimum.
-   */
-  cpu?: number | null;
-  memory?: number | null;
-  disk?: number | null;
 }
 
 /**
@@ -172,11 +117,6 @@ export function upsertDeployedSystem(
       machineId: system.machineId ?? null,
       serviceId: system.serviceId ?? null,
       vmid: system.vmid ?? null,
-      // Seed-once (ISS-0150): set on insert; deliberately omitted from the
-      // conflict update below so a resize survives re-deploys.
-      cpu: system.cpu ?? null,
-      memory: system.memory ?? null,
-      disk: system.disk ?? null,
       updatedAt: new Date(),
     })
     .onConflictDoUpdate({
@@ -189,9 +129,6 @@ export function upsertDeployedSystem(
         machineId: system.machineId ?? null,
         serviceId: system.serviceId ?? null,
         vmid: system.vmid ?? null,
-        // NOTE: cpu/memory/disk intentionally NOT updated here — sizing is
-        // canonical state owned by `celilo proxmox … resize`, not reset by a
-        // routine re-deploy (seed-once). See ISS-0150 / CLAUDE.md.
         updatedAt: new Date(),
       },
     })
@@ -270,11 +207,6 @@ export async function recordDeployedSystemForModule(
     machineId: infrastructure?.machineId ?? null,
     serviceId: infrastructure?.serviceId ?? null,
     vmid: Number.isNaN(vmid as number) ? null : vmid,
-    // Seed canonical size from requires.system (seed-once; preserved across
-    // re-deploys). Only meaningful for celilo-provisioned instances.
-    cpu: decl.resources.cpu ?? null,
-    memory: decl.resources.memory ?? null,
-    disk: decl.resources.disk ?? null,
   });
 
   return getModuleSystems(moduleId, db);
@@ -347,10 +279,6 @@ export function backfillModuleSystems(db: DbClient): string[] {
       machineId: infra.machineId ?? null,
       serviceId: infra.serviceId ?? null,
       vmid: vmid != null && !Number.isNaN(vmid) ? vmid : null,
-      // Seed canonical size from requires.system for upgraded deployments.
-      cpu: decl.resources.cpu ?? null,
-      memory: decl.resources.memory ?? null,
-      disk: decl.resources.disk ?? null,
     });
     backfilled.push(infra.moduleId);
   }

package/src/services/module-validator/git-hygiene.test.ts

@@ -122,6 +122,41 @@ describe('checkGitHygiene', () => {
     }
   });
 
+  test('skips the stale gate for version_source: changeset (apps order by +N)', () => {
+    const repo = makeTempRepo();
+    try {
+      // Same stale shape that fails above — src committed after manifest.
+      writeFileSync(join(repo.dir, 'manifest.yml'), 'id: x\nversion: 1.0.0\n');
+      repo.exec('git add . && git commit -q -m "manifest"');
+      writeFileSync(join(repo.dir, 'install.sh'), '#!/bin/sh\n');
+      repo.exec('git add . && git commit -q -m "src after manifest"');
+
+      const stale = checkGitHygiene(repo.dir, 'changeset').find(
+        (c) => c.name === 'stale-version drift',
+      );
+      expect(stale?.status).toBe('ok'); // gate N/A, not a fail
+      expect(stale?.message).toContain('changeset');
+    } finally {
+      repo.cleanup();
+    }
+  });
+
+  test('skips the stale gate for version_source: pin', () => {
+    const repo = makeTempRepo();
+    try {
+      writeFileSync(join(repo.dir, 'manifest.yml'), 'id: x\nversion: 1.0.0\n');
+      repo.exec('git add . && git commit -q -m "manifest"');
+      writeFileSync(join(repo.dir, 'install.sh'), '#!/bin/sh\n');
+      repo.exec('git add . && git commit -q -m "src after manifest"');
+
+      const stale = checkGitHygiene(repo.dir, 'pin').find((c) => c.name === 'stale-version drift');
+      expect(stale?.status).toBe('ok');
+      expect(stale?.message).toContain('pin');
+    } finally {
+      repo.cleanup();
+    }
+  });
+
   test('warn on dirty working tree', () => {
     const repo = makeTempRepo();
     try {

package/src/services/module-validator/git-hygiene.ts

@@ -85,30 +85,49 @@ export function checkModuleStale(moduleDir: string): StalenessIssue | null {
  * directory tarball, etc.) — git operations return null/empty and we
  * skip the check.
  */
-export function checkGitHygiene(modulePath: string): Check[] {
+export function checkGitHygiene(modulePath: string, versionSourceKind?: string): Check[] {
   const checks: Check[] = [];
 
-  const stale = checkModuleStale(modulePath);
-  if (stale) {
-    checks.push({
-      category: 'git_hygiene',
-      name: 'stale-version drift',
-      status: 'fail',
-      message: [
-        'src commits past last manifest.yml change',
-        `  src commit:        ${stale.lastSrcCommit.slice(0, 12)}`,
-        `  manifest.yml commit: ${stale.lastManifestCommit.slice(0, 12)}`,
-        '  Bump manifest.yml#version (semver change), or touch it',
-        '  (release-only — auto-revision picks the next +N), then commit.',
-      ].join('\n'),
-    });
-  } else {
+  // The source-after-manifest stale gate guards a HAND-MAINTAINED module's
+  // version (the default — `recipe` kind / unset version_source). For
+  // changeset-versioned modules the version is authored via .changeset/ +
+  // `celilo module version` and ordered by the +N revision, so source moving
+  // past the manifest is the NORMAL case, not drift; for pin modules the version
+  // is checked against the upstream resolver, not git ancestry. Skip the gate for
+  // both (v2/MODULE_VERSIONING.md / ISS-0151).
+  if (versionSourceKind === 'changeset' || versionSourceKind === 'pin') {
     checks.push({
       category: 'git_hygiene',
       name: 'stale-version drift',
       status: 'ok',
-      message: 'manifest.yml is current with respect to module src',
+      message:
+        versionSourceKind === 'changeset'
+          ? 'version_source: changeset — changeset-authored version, ordered by +N; source-after-manifest gate N/A'
+          : 'version_source: pin — version checked against the upstream resolver, not git ancestry',
     });
+  } else {
+    const stale = checkModuleStale(modulePath);
+    if (stale) {
+      checks.push({
+        category: 'git_hygiene',
+        name: 'stale-version drift',
+        status: 'fail',
+        message: [
+          'src commits past last manifest.yml change',
+          `  src commit:        ${stale.lastSrcCommit.slice(0, 12)}`,
+          `  manifest.yml commit: ${stale.lastManifestCommit.slice(0, 12)}`,
+          '  Bump manifest.yml#version (semver change), or touch it',
+          '  (release-only — auto-revision picks the next +N), then commit.',
+        ].join('\n'),
+      });
+    } else {
+      checks.push({
+        category: 'git_hygiene',
+        name: 'stale-version drift',
+        status: 'ok',
+        message: 'manifest.yml is current with respect to module src',
+      });
+    }
   }
 
   try {

package/src/services/module-validator/index.ts

@@ -21,6 +21,7 @@ export { checkWorkspaceDeps, defaultFetchNpmMetadata } from './workspace-deps';
 
 interface RawManifest extends ManifestForCapabilityCheck {
   celilo_contract?: string;
+  version_source?: { kind?: string };
 }
 
 /**
@@ -67,7 +68,7 @@ export async function runChecks(
   }
 
   checks.push(...(await checkWorkspaceDeps(modulePath, fetcher)));
-  checks.push(...checkGitHygiene(modulePath));
+  checks.push(...checkGitHygiene(modulePath, manifest?.version_source?.kind));
   checks.push(await checkTypeScriptBuild(modulePath, { noBuild: options.noBuild }));
 
   return checks;