@warpgogol/werkstatt-shared 0.14.0 → 0.15.0

package/src/semantic/tests/update-stamp.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it } from "vitest";
+import {
+  isValidStampDate,
+  resolveAuthoredStamp,
+  resolveCklStamp,
+  resolvePageUpdateStamp,
+} from "../update-stamp.ts";
+
+describe("isValidStampDate", () => {
+  it("accepts YYYY-MM-DD", () => {
+    expect(isValidStampDate("2024-01-15")).toBe(true);
+  });
+
+  it("rejects non-string", () => {
+    expect(isValidStampDate(20240115)).toBe(false);
+  });
+
+  it("rejects wrong format", () => {
+    expect(isValidStampDate("2024/01/15")).toBe(false);
+    expect(isValidStampDate("January 15, 2024")).toBe(false);
+  });
+});
+
+describe("resolveAuthoredStamp", () => {
+  it("uses output.sitemap.lastmod first", () => {
+    const result = resolveAuthoredStamp({
+      output: { sitemap: { lastmod: "2024-06-01" } },
+    });
+    expect(result?.date).toBe("2024-06-01");
+    expect(result?.source).toBe("authored-system-output");
+  });
+
+  it("uses article.updatedAt when no sitemap lastmod", () => {
+    const result = resolveAuthoredStamp({
+      article: { updatedAt: "2024-05-01" },
+    });
+    expect(result?.date).toBe("2024-05-01");
+    expect(result?.source).toBe("authored-page-frontmatter");
+  });
+
+  it("uses article.publishedAt when no updatedAt", () => {
+    const result = resolveAuthoredStamp({
+      article: { publishedAt: "2024-01-01" },
+    });
+    expect(result?.date).toBe("2024-01-01");
+  });
+
+  it("returns undefined when no valid dates", () => {
+    expect(resolveAuthoredStamp({})).toBeUndefined();
+  });
+
+  it("ignores invalid date formats", () => {
+    expect(resolveAuthoredStamp({ article: { updatedAt: "not-a-date" } })).toBeUndefined();
+  });
+});
+
+describe("resolveCklStamp", () => {
+  it("returns latest valid date", () => {
+    const result = resolveCklStamp(["2024-01-01", "2024-06-15", "2024-03-01"], ["ledger"]);
+    expect(result?.date).toBe("2024-06-15");
+    expect(result?.source).toBe("ckl-claim-ledger");
+  });
+
+  it("returns undefined when no valid dates", () => {
+    expect(resolveCklStamp(["invalid"], ["ledger"])).toBeUndefined();
+  });
+});
+
+describe("resolvePageUpdateStamp", () => {
+  it("prefers authored stamp over CKL", () => {
+    const result = resolvePageUpdateStamp({
+      pageId: "p1",
+      lang: "de",
+      pageEntry: { output: { sitemap: { lastmod: "2024-06-01" } } },
+      cklLedgerDates: ["2024-01-01"],
+    });
+    expect(result.stamp?.date).toBe("2024-06-01");
+    expect(result.stamp?.source).toBe("authored-system-output");
+  });
+
+  it("falls back to CKL when no authored stamp", () => {
+    const result = resolvePageUpdateStamp({
+      pageId: "p1",
+      lang: "de",
+      pageEntry: {},
+      cklLedgerDates: ["2024-03-01"],
+      cklInputs: ["ledger"],
+    });
+    expect(result.stamp?.date).toBe("2024-03-01");
+    expect(result.stamp?.source).toBe("ckl-claim-ledger");
+  });
+
+  it("returns missingReason when no sources available", () => {
+    const result = resolvePageUpdateStamp({
+      pageId: "p1",
+      lang: "de",
+      pageEntry: {},
+    });
+    expect(result.stamp).toBeUndefined();
+    expect(result.missingReason).toBe("no-content-source");
+  });
+});

package/src/signing/index.ts

@@ -0,0 +1,13 @@
+/*
+<MODULE_CONTRACT>
+  <purpose>Barrel export for @warpgogol/werkstatt-shared/signing sub-path. Re-exports the Ed25519 signing core (key generation, sign/verify, signing types) sunk from @warpgogol/werkstatt-engine per RFC-1104.</purpose>
+  <non-goals>Does not re-export engine signing commands (signing-commands.ts stays in engine).</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1104: initial barrel — signing core sunk from werkstatt-engine.</item>
+</CHANGE_SUMMARY>
+*/
+
+export * from "./types.ts";
+export * from "./key.ts";
+export * from "./sign.ts";

package/src/signing/key.ts

@@ -0,0 +1,139 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0921: Shared Ed25519 key management — generation, loading, saving, and encoding helpers.</purpose>
+
+
+<non-goals>
+  <item>Does not implement signing or verification — those live in sign.ts.</item>
+  <item>Does not manage key publication or key rotation — domain-specific concerns belong in consumers.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0921: initial signing key management module.</item>
+  <item>RFC-1097: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
+  <item>RFC-1097: sweep — werkstatt-engine clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
+</CHANGE_SUMMARY>
+*/
+
+import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { createPrivateKey, createPublicKey } from "node:crypto";
+import * as ed from "@noble/ed25519";
+import type { KeyEncoding, SigningKeyPair } from "./types.ts";
+
+export async function generateKeyPair(): Promise<SigningKeyPair> {
+  const privateKey = ed.utils.randomSecretKey();
+  const publicKey = await getPublicKey(privateKey);
+  return { privateKey, publicKey };
+}
+
+export async function getPublicKey(privateKey: Uint8Array): Promise<Uint8Array> {
+  return ed.getPublicKeyAsync(privateKey);
+}
+
+export async function loadPrivateKey(
+  source: { pem: string } | { hex: string } | { filePath: string; encoding: KeyEncoding },
+): Promise<Uint8Array> {
+  if ("pem" in source) {
+    return fromPem(source.pem);
+  }
+  if ("hex" in source) {
+    return fromHex(source.hex);
+  }
+  const raw = (await fs.readFile(source.filePath, "utf8")).trim();
+  if (source.encoding === "pem") {
+    return fromPem(raw);
+  }
+  return fromHex(raw);
+}
+
+export async function loadPublicKey(
+  source: { pem: string } | { hex: string } | { filePath: string; encoding: KeyEncoding },
+): Promise<Uint8Array> {
+  if ("pem" in source) {
+    return fromPem(source.pem);
+  }
+  if ("hex" in source) {
+    return fromHex(source.hex);
+  }
+  const raw = (await fs.readFile(source.filePath, "utf8")).trim();
+  if (source.encoding === "pem") {
+    return fromPem(raw);
+  }
+  return fromHex(raw);
+}
+
+export async function saveKeyPair(
+  keyPair: SigningKeyPair,
+  outputDir: string,
+  encoding: KeyEncoding,
+): Promise<{ privateKeyPath: string; publicKeyPath: string }> {
+  await fs.mkdir(outputDir, { recursive: true });
+
+  const privateKeyPath = path.join(outputDir, `signing.key${encoding === "pem" ? ".pem" : ""}`);
+  const publicKeyPath = path.join(outputDir, `signing.key.pub${encoding === "pem" ? ".pem" : ""}`);
+
+  if (encoding === "pem") {
+    await fs.writeFile(privateKeyPath, toPem(keyPair.privateKey, "private"), "utf8");
+    await fs.writeFile(publicKeyPath, toPem(keyPair.publicKey, "public"), "utf8");
+  } else {
+    await fs.writeFile(privateKeyPath, toHex(keyPair.privateKey), "utf8");
+    await fs.writeFile(publicKeyPath, toHex(keyPair.publicKey), "utf8");
+  }
+
+  return { privateKeyPath, publicKeyPath };
+}
+
+export function toHex(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString("hex");
+}
+
+export function fromHex(hex: string): Uint8Array {
+  return new Uint8Array(Buffer.from(hex, "hex"));
+}
+
+export function toPem(bytes: Uint8Array, type: "private" | "public"): string {
+  const label = type === "private" ? "PRIVATE KEY" : "PUBLIC KEY";
+  const base64 = Buffer.from(bytes).toString("base64");
+  const lines = base64.match(/.{1,64}/g) ?? [base64];
+  return `-----BEGIN ${label}-----\n${lines.join("\n")}\n-----END ${label}-----\n`;
+}
+
+export function fromPem(pem: string): Uint8Array {
+  const base64 = pem
+    .replace(/-----BEGIN [A-Z ]+-----/g, "")
+    .replace(/-----END [A-Z ]+-----/g, "")
+    .replace(/\s+/g, "");
+  return new Uint8Array(Buffer.from(base64, "base64"));
+}
+
+export function privateKeyPemToBytes(pem: string): Uint8Array {
+  const key = createPrivateKey(pem);
+  if (key.asymmetricKeyType !== "ed25519") {
+    throw new Error(
+      `Wrong private key type: ${key.asymmetricKeyType ?? "unknown"}. Expected ed25519.`,
+    );
+  }
+  const jwk = key.export({ format: "jwk" }) as { d: string };
+  return new Uint8Array(Buffer.from(jwk.d, "base64url"));
+}
+
+export function publicKeyPemToBytes(pem: string): Uint8Array {
+  const key = createPublicKey(pem);
+  if (key.asymmetricKeyType !== "ed25519") {
+    throw new Error(
+      `Wrong public key type: ${key.asymmetricKeyType ?? "unknown"}. Expected ed25519.`,
+    );
+  }
+  const jwk = key.export({ format: "jwk" }) as { x: string };
+  return new Uint8Array(Buffer.from(jwk.x, "base64url"));
+}
+
+export function keyExists(filePath: string): boolean {
+  return existsSync(filePath);
+}

package/src/signing/sign.ts

@@ -0,0 +1,66 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0921: Shared Ed25519 sign/verify primitives — canonicalization, raw byte signing, and convenience wrappers.</purpose>
+
+
+<non-goals>
+  <item>Does not implement key generation or loading — those live in key.ts.</item>
+  <item>Does not implement multibase encoding — that is a Cosmic Passport concern.</item>
+  <item>Does not implement Bordbuch or manifest storage — those are consumer concerns.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0921: initial signing primitives module.</item>
+  <item>RFC-1097: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
+  <item>RFC-1097: sweep — werkstatt-engine clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
+</CHANGE_SUMMARY>
+*/
+
+import * as ed from "@noble/ed25519";
+import {
+  snapshotCanonicalJsonObjectV1,
+  canonicalJsonBytesV1,
+} from "../fingerprint/canonical-json.ts";
+import type { SignablePayload } from "./types.ts";
+
+export function canonicalBytes(payload: SignablePayload): Uint8Array {
+  const snapshot = snapshotCanonicalJsonObjectV1(payload);
+  if (!snapshot.ok) {
+    throw new Error(
+      `CERT-CANONICAL-SNAPSHOT-01: failed to canonicalize payload (${snapshot.code})`,
+    );
+  }
+  return canonicalJsonBytesV1(snapshot.value);
+}
+
+export async function signBytes(privateKey: Uint8Array, message: Uint8Array): Promise<Uint8Array> {
+  return ed.signAsync(message, privateKey);
+}
+
+export async function verifyBytes(
+  publicKey: Uint8Array,
+  message: Uint8Array,
+  signature: Uint8Array,
+): Promise<boolean> {
+  try {
+    return await ed.verifyAsync(signature, message, publicKey);
+  } catch {
+    return false;
+  }
+}
+
+export async function sign(privateKey: Uint8Array, payload: SignablePayload): Promise<Uint8Array> {
+  return signBytes(privateKey, canonicalBytes(payload));
+}
+
+export async function verify(
+  publicKey: Uint8Array,
+  payload: SignablePayload,
+  signature: Uint8Array,
+): Promise<boolean> {
+  return verifyBytes(publicKey, canonicalBytes(payload), signature);
+}

package/src/signing/types.ts

@@ -0,0 +1,29 @@
+/*
+<MODULE_CONTRACT>
+<purpose>RFC-0921: Shared Ed25519 signing core types — used by Nachweis, Integrity, and Cosmic Passport.</purpose>
+
+
+<non-goals>
+  <item>Does not implement signing or key generation logic — those live in sign.ts and key.ts.</item>
+  <item>Does not define domain-specific payload shapes — consumers define their own and pass them as Record&lt;string, unknown&gt;.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-0921: initial signing core types module.</item>
+  <item>RFC-1097: step 6 — compass.migrate codemod run
+
+Mechanical v1 to v2 header migration across the workspace: 942 files rewritten — CHANGE_SUMMARY windows collapsed into history, forbidden v1 blocks stripped, KEY_DECISIONS seeded from @ai-invariant comments (5 files) or TODO placeholders (103 files), blocks reordered to canonical order.</item>
+  <item>RFC-1097: sweep — werkstatt-engine clean
+
+Sweep batch 4: 73 Compass headers on headerless engine files (certification, component-runtime, isolation, evolution, testing), real KEY_DECISIONS on 75 files (kernel, cache, dht, swim, gitmesh, runtime), ~80 purpose expansions (CONTRACT-02/PURPOSE-02), non-goals on 13 CONTRACT-03 files, CS-07 history literal fix repo-wide (253 files). Policy: .template.ts/.template.astro excludedPaths. werkstatt-engine now 0 diagnostics.</item>
+</CHANGE_SUMMARY>
+*/
+
+export type KeyEncoding = "pem" | "hex";
+
+export interface SigningKeyPair {
+  privateKey: Uint8Array;
+  publicKey: Uint8Array;
+}
+
+export type SignablePayload = Record<string, unknown>;

package/src/{share/slug → slug}/slug-url.ts

@@ -1,12 +1,15 @@
 /*
 <MODULE_CONTRACT>
-<purpose>Canonical locale-aware URL slug generation (RFC-0915, DNA-88).</purpose>
+<purpose>slug-url — canonical locale-aware URL slug generation for site routes (RFC-0915, DNA-88).</purpose>
 <non-goals>
   <item>Do not handle heading anchor deduplication — use HeadingSlugger for that.</item>
 </non-goals>
 </MODULE_CONTRACT>
 <CHANGE_SUMMARY>
   <item>RFC-0915: extracted from werkstatt-site/src/domain/geo/slug.ts as canonical URL slug function.</item>
+  <item>RFC-1097: sweep — tail packages clean
+
+Sweep batch 3: rewrote ~95 purposes across werkstatt-knowledge, werkstatt-shared, godot-game, phaser-game, lifecycle-core, projektarchiv-*, portal-*, billing-*, typescript (CONTRACT-02/PURPOSE-02). Real KEY_DECISIONS on 5 godot utils, non-goals on 5 CONTRACT-03 files, headers on 4 headerless files, CS-07 history literal fix on 2 files. Policy: vitest.config.ts + test-fixtures testPatterns, worker-configuration.d.ts excludedPath. All non-site/engine packages now 0 diagnostics.</item>
 </CHANGE_SUMMARY>
 */
 

package/src/stack/run-tool.ts

@@ -0,0 +1,108 @@
+/*
+<MODULE_CONTRACT>
+<purpose>runTool — the single subprocess seam for stack plugins (RFC-1100). Owns the
+shared prologue every external-binary call needs: dist/ preflight, required-env
+presence check, env merge, timeout, and error mapping to ToolResult. Production
+uses the default execFileSync adapter; tests inject a recording ToolExecutor so no
+test mocks node:child_process.</purpose>
+
+<non-goals>
+  <item>Does not validate tool-specific config — callers check their own config fields before calling runTool.</item>
+  <item>Does not use shell interpolation — execFile with an argument array only (DNA-89).</item>
+  <item>Does not run in the browser — server-only (Node child_process).</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1100: initial subprocess seam — runTool + ToolSpec/ToolResult/ToolExecutor; replaces per-call-site execFileSync prologues in stack plugins.</item>
+  <item>RFC-1100: step 1 — shared tool/fs/check seams (walkFiles, runTool, defineStackChecks)</item>
+</CHANGE_SUMMARY>
+*/
+
+// Server-only. Do not import from browser/client scripts.
+
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+export interface ToolSpec {
+  /** Binary to execute, e.g. "npx". */
+  bin: string;
+  /** Argument array — never a shell string (DNA-89). */
+  args: string[];
+  /** Working directory for the subprocess. */
+  cwd: string;
+  /** Extra environment merged over process.env for the subprocess. */
+  env?: Record<string, string>;
+  /** Subprocess timeout. Default 120_000 ms. */
+  timeoutMs?: number;
+  /** Preflight: require <cwd>/dist to exist before executing. */
+  requireDist?: boolean;
+  /** Preflight: require these env vars to be non-empty after the env merge. */
+  requireEnv?: string[];
+}
+
+export interface ToolResult {
+  success: boolean;
+  stdout?: string;
+  errors?: string[];
+  /** Which phase produced the failure — lets callers keep preflight messages unwrapped. */
+  failedAt?: "preflight" | "exec";
+}
+
+/**
+ * Executes a ToolSpec. Injectable so tests record specs instead of spawning
+ * processes — pass a fake that captures the spec and returns a canned ToolResult.
+ */
+export type ToolExecutor = (spec: ToolSpec) => ToolResult;
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+const execFileExecutor: ToolExecutor = (spec) => {
+  try {
+    const stdout = execFileSync(spec.bin, spec.args, {
+      cwd: spec.cwd,
+      encoding: "utf-8",
+      timeout: spec.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      stdio: ["pipe", "pipe", "pipe"],
+      env: { ...process.env, ...spec.env },
+    });
+    return { success: true, stdout };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { success: false, errors: [message], failedAt: "exec" };
+  }
+};
+
+export function runTool(spec: ToolSpec, executor: ToolExecutor = execFileExecutor): ToolResult {
+  if (spec.requireDist) {
+    const distDir = join(spec.cwd, "dist");
+    if (!existsSync(distDir)) {
+      return {
+        success: false,
+        errors: [`dist/ directory not found at ${distDir} — run build first`],
+        failedAt: "preflight",
+      };
+    }
+  }
+
+  if (spec.requireEnv && spec.requireEnv.length > 0) {
+    const mergedEnv = { ...process.env, ...spec.env };
+    const missing = spec.requireEnv.filter((name) => !mergedEnv[name]);
+    if (missing.length > 0) {
+      return {
+        success: false,
+        errors: missing.map(
+          (name) => `Required environment variable ${name} is not set`,
+        ),
+        failedAt: "preflight",
+      };
+    }
+  }
+
+  try {
+    return executor(spec);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { success: false, errors: [message], failedAt: "exec" };
+  }
+}

package/src/stack/stack-checks.ts

@@ -0,0 +1,124 @@
+/*
+<MODULE_CONTRACT>
+<purpose>defineStackChecks — the spec-driven check harness for stack plugins
+(RFC-1100). A plugin declares one StackCheckSpec table; the harness derives kernel
+command declarations, the checkGate hook body, and invariant table rows from it.
+Validator files keep only a pure check() function — they never shape
+KernelCommandResult or register commands themselves.</purpose>
+
+<non-goals>
+  <item>Does not implement stack-specific rules — those live in the plugin's check() functions.</item>
+  <item>Does not read files — check() functions consume the plugin's model/walker seams.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1100: initial spec-driven check harness — StackCheckSpec, StackCheckViolation, StackCheckData, defineStackChecks returning commands + runCheckGate + invariantRows.</item>
+  <item>RFC-1100: step 1 — shared tool/fs/check seams (walkFiles, runTool, defineStackChecks)</item>
+</CHANGE_SUMMARY>
+*/
+
+import type {
+  KernelCommandDefinition,
+  KernelCommandResult,
+} from "@warpgogol/werkstatt-shared/kernel";
+import type { HookResult, PluginHookContext } from "../plugin/plugin-contract.ts";
+
+/** A single rule violation emitted by a stack check() function. */
+export interface StackCheckViolation {
+  ruleId: string;
+  file: string;
+  message: string;
+  line?: number;
+  details?: Record<string, unknown>;
+}
+
+/** Uniform data payload every stack check command returns. */
+export interface StackCheckData {
+  command: string;
+  status: "pass" | "fail";
+  violations: StackCheckViolation[];
+}
+
+export interface StackCheckSpec {
+  /** Kernel command name, e.g. "phaser.scenes.validate". */
+  name: string;
+  /** Human-readable command description. */
+  description: string;
+  /** The single contract this check enforces (DNA-91). */
+  contract: string;
+  /** Rule IDs this check emits (DNA-91). */
+  rules: string[];
+  /** Workspace-relative path globs this check reads (RFC-0266). */
+  reads: string[];
+  /** Invariant ID for invariantRows — defaults to rules[0]. */
+  invariantId?: string;
+  /** Pure rule logic: project root in, violations out. */
+  check: (projectRoot: string) => Promise<StackCheckViolation[]>;
+}
+
+export interface StackCheckDeclarations {
+  /** Kernel command declarations, one per spec entry. */
+  commands: KernelCommandDefinition<StackCheckData>[];
+  /** The plugin's checkGate hook body — runs every spec in order. */
+  runCheckGate: (ctx: PluginHookContext) => Promise<HookResult>;
+  /** Invariant table rows derived from the spec — { id, command } pairs. */
+  invariantRows: Array<{ id: string; command: string }>;
+}
+
+function toCommand(spec: StackCheckSpec): KernelCommandDefinition<StackCheckData> {
+  return {
+    name: spec.name,
+    description: spec.description,
+    contract: spec.contract,
+    rules: spec.rules,
+    reads: spec.reads,
+    scope: "workspace",
+    cacheable: false,
+    async execute(_input, context): Promise<KernelCommandResult<StackCheckData>> {
+      const violations = await spec.check(context.workspaceRoot);
+      const status = violations.length === 0 ? "pass" : "fail";
+      return {
+        data: { command: spec.name, status, violations },
+        exitCode: status === "pass" ? 0 : 1,
+        summary: `${spec.name}: ${status} (${violations.length} violations)`,
+      };
+    },
+  };
+}
+
+/** Short gate-log label: "phaser.scenes.validate" → "scenes". */
+function gateLabel(commandName: string): string {
+  return commandName.split(".")[1] ?? commandName;
+}
+
+export function defineStackChecks(specs: StackCheckSpec[]): StackCheckDeclarations {
+  const commands = specs.map(toCommand);
+
+  async function runCheckGate(ctx: PluginHookContext): Promise<HookResult> {
+    const projectRoot = ctx.workpiecePath ?? ctx.workspaceRoot;
+    const errors: string[] = [];
+    const statuses: string[] = [];
+
+    for (const spec of specs) {
+      const violations = await spec.check(projectRoot);
+      const status = violations.length === 0 ? "pass" : "fail";
+      statuses.push(`${gateLabel(spec.name)}=${status}`);
+      if (violations.length > 0) {
+        errors.push(`${spec.name}: ${violations.length} violations`);
+      }
+    }
+
+    ctx.logger.info(`checkGate: ${statuses.join(", ")}`);
+
+    return {
+      success: errors.length === 0,
+      errors: errors.length > 0 ? errors : undefined,
+    };
+  }
+
+  const invariantRows = specs
+    .map((spec) => ({ id: spec.invariantId ?? spec.rules[0], command: spec.name }))
+    .filter((row): row is { id: string; command: string } => typeof row.id === "string");
+
+  return { commands, runCheckGate, invariantRows };
+}