@platforma-sdk/block-tools 2.10.19 → 2.11.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@platforma-sdk/block-tools",
-  "version": "2.10.19",
+  "version": "2.11.1",
   "description": "Utility to manipulate Platforma Blocks and Block Registry",
   "license": "UNLICENSED",
   "bin": {
@@ -34,13 +34,13 @@
     "yaml": "^2.8.0",
     "zod": "~3.25.76",
     "@milaboratories/pl-http": "1.2.4",
-    "@milaboratories/pl-model-common": "1.46.1",
-    "@milaboratories/pl-model-middle-layer": "1.30.6",
-    "@milaboratories/resolve-helper": "1.1.3",
+    "@milaboratories/pl-model-backend": "1.4.8",
+    "@milaboratories/pl-model-common": "1.46.2",
+    "@milaboratories/ts-helpers": "1.8.3",
+    "@milaboratories/pl-model-middle-layer": "1.30.7",
     "@milaboratories/ts-helpers-oclif": "1.1.42",
     "@platforma-sdk/blocks-deps-updater": "2.2.0",
-    "@milaboratories/ts-helpers": "1.8.3",
-    "@milaboratories/pl-model-backend": "1.4.7"
+    "@milaboratories/resolve-helper": "1.1.3"
   },
   "devDependencies": {
     "@rollup/plugin-node-resolve": "^16.0.1",

package/src/structure/CLAUDE.md

@@ -15,12 +15,14 @@ To change what "canonical" means, edit `rules/`; the engine is block-agnostic.
 
 - Each `rules/*` file pairs a generator (init: full initial content) with a body (refresh: drift-correcting assertions). Read as "what the file should be" + "how to nudge an existing file there", not as sequential logic.
 - The primitive choice IS the design: `fixed` (overwrite verbatim, engine-owned), `managed` (reconcile named fields, author keeps the rest), `scaffold` (write-once default, author may tune), `seed` (written once at init, author owns forever), `remove` (one-way). Wrong primitive is the main design error — `fixed` on an author-tunable file clobbers their work; `seed` on engine-owned content lets drift accumulate.
+- Two layers. Calls inside `defineStructure` (`scope`/`fixed`/`managed`/`seed`/`when`-framing) run once at tree-build time to DECLARE the tree — there is no block and no `ctx` yet. The lambdas the engine runs later, per block — trigger predicates, `generate`/`tpl` producers, and `managed` bodies — are the EXECUTION layer, where per-block values are computed.
 
 ## Invariants
 
 - Fixpoint: `refresh` on an already-canonical block makes zero changes. Every rule must converge.
 - Generators emit oxfmt-clean output (the `enforce*` calls mirror oxfmt's order), so build→check passes with no prior `fmt`.
 - sdk-internal blocks (`etc/blocks/*`) skip root-scope and standalone test wiring — the monorepo owns that infra; the structurer must neither impose nor strip it.
+- Rule code never reaches for `ctx` ambiently — `getActiveRunContext()`/`blockVars()` are engine-internal plumbing. A lambda that needs block identity takes `ctx` by argument (triggers get the richer `TriggerContext`, the rest `RunContext`); a `managed` body that doesn't take it relies on the builders it calls, which resolve `ctx` themselves.
 
 ## Gotchas
 

package/src/structure/__tests__/discovery-shortname.test.ts

@@ -0,0 +1,50 @@
+// DISCOVERY derives BlockVars from the block-scope module's package name.
+// This structurer names that package `<facade>.block`, while the root
+// package carries no `name` — so on refresh/check the `.block` suffix would
+// leak into `shortName` unless discovery strips it (see discovery-fs.ts).
+// These tests pin both shapes: the structurer-shaped block (suffix stripped)
+// and a legacy block whose block package IS the bare facade (nothing to
+// strip).
+
+import { describe, test, expect } from "vitest";
+import type { BlockVars } from "../engine/api";
+import { simulateInit } from "../engine/testing";
+import { discoverRunContext } from "../engine/discovery-fs";
+import { MemoryFileSystem } from "../engine/fs/memory";
+
+describe("DISCOVERY: shortName from the block package name", () => {
+  test("strips the trailing .block for a <facade>.block-shaped block", () => {
+    const vars: BlockVars = {
+      facadeName: "@platforma-open/test-org.demo",
+      baseName: "test-org.demo",
+      npmOrg: "@platforma-open",
+      orgScope: "test-org",
+      shortName: "demo",
+    };
+    // simulateInit runs the real init then RE-DISCOVERS from the written FS,
+    // so this is the genuine refresh/check derivation path.
+    const { ctx } = simulateInit({ vars });
+    // Sanity: the block package really is named `<facade>.block` on disk.
+    const blockMod = ctx.modules.find((m) => m.scope === "block");
+    expect(blockMod?.name).toBe("@platforma-open/test-org.demo.block");
+    expect(ctx.blockVars.shortName).toBe("demo");
+  });
+
+  test("keeps the real shortName for a legacy bare-facade block package", () => {
+    const fs = new MemoryFileSystem({
+      "pnpm-workspace.yaml": "packages:\n  - block\n",
+      // Nameless root — the standalone shape; classified `root` by path.
+      "package.json": "{}",
+      // Legacy block package: name IS the bare facade, no `.block` suffix.
+      "block/package.json": JSON.stringify({
+        name: "@platforma-open/test-org.legacy",
+        files: ["index.d.ts", "index.js"],
+        dependencies: { "@platforma-sdk/block-tools": "*" },
+      }),
+    });
+    const ctx = discoverRunContext({ fs, isSdkInternal: false });
+    const blockMod = ctx.modules.find((m) => m.scope === "block");
+    expect(blockMod?.name).toBe("@platforma-open/test-org.legacy");
+    expect(ctx.blockVars.shortName).toBe("legacy");
+  });
+});

package/src/structure/__tests__/root-ci-workflows.test.ts

@@ -0,0 +1,68 @@
+// Root CI workflow files (`rules/root-ci.ts`) — `fixed`, generated from the
+// block's short name. These rules are `!isSdkInternal`, so the `etc/blocks`
+// check-blocks run never exercises them; this is their only coverage.
+//
+// Asserts: init writes both workflows with derived identity (app-name /
+// app-name-slug) + shared constants (team-id, the `@v4` pins, test: true);
+// the files are idempotent (init → check zero diff); and `--sdk-internal`
+// blocks get neither file.
+
+import { describe, test, expect } from "vitest";
+import type { BlockVars, RunContext } from "../engine/api";
+import { STRUCTURE } from "../structure-definition";
+import { run as engineRun } from "../engine/runner";
+import { defaultTemplateProvider, simulateInit } from "../engine/testing";
+
+const TEMPLATES = defaultTemplateProvider();
+
+const VARS: BlockVars = {
+  facadeName: "@platforma-open/milaboratories.mixcr-clonotyping-2",
+  baseName: "milaboratories.mixcr-clonotyping-2",
+  npmOrg: "@platforma-open",
+  orgScope: "milaboratories",
+  shortName: "mixcr-clonotyping-2",
+};
+
+const BUILD = ".github/workflows/build.yaml";
+const MARK_STABLE = ".github/workflows/mark-stable.yaml";
+
+describe("root CI workflows (fixed, generated)", () => {
+  test("init writes both workflows with derived identity + shared constants", () => {
+    const { fs } = simulateInit({ vars: VARS });
+
+    const build = fs.read(BUILD);
+    // Derived identity from the short name.
+    expect(build).toContain("app-name: 'Block: Mixcr Clonotyping 2'");
+    expect(build).toContain("app-name-slug: 'block-mixcr-clonotyping-2'");
+    // Shared constants.
+    expect(build).toContain("team-id: 'ciplopen'");
+    expect(build).toContain("test: true");
+    // The reusable-workflow pins — the whole point of engine-owning the file.
+    expect(build).toContain(
+      "uses: milaboratory/github-ci/.github/workflows/node-simple-pnpm.yaml@v4",
+    );
+    expect(build).toContain("uses: milaboratory/github-ci/actions/context/init@v4");
+    // `${{ ... }}` GitHub expressions survive `tpl` substitution untouched.
+    expect(build).toContain("${{ toJSON(secrets.NPMJS_TOKEN) }}");
+
+    const markStable = fs.read(MARK_STABLE);
+    expect(markStable).toContain("app-name: 'Block: Mixcr Clonotyping 2 - Mark Stable'");
+    expect(markStable).toContain(
+      "uses: milaboratory/github-ci/.github/workflows/block-mark-stable.yaml@v4",
+    );
+  });
+
+  test("init → check is zero-diff for the workflow files (fixed idempotency)", () => {
+    const { fs, ctx } = simulateInit({ vars: VARS });
+    const checkCtx: RunContext = { ...ctx, dryRun: true };
+    const result = engineRun(STRUCTURE, fs, checkCtx, { templates: TEMPLATES });
+    const ciChanges = result.changes.filter((c) => c.path === BUILD || c.path === MARK_STABLE);
+    expect(ciChanges).toEqual([]);
+  });
+
+  test("sdk-internal blocks get neither workflow file", () => {
+    const { fs } = simulateInit({ vars: VARS, isSdkInternal: true });
+    expect(fs.exists(BUILD)).toBe(false);
+    expect(fs.exists(MARK_STABLE)).toBe(false);
+  });
+});

package/src/structure/engine/builders.ts

@@ -327,18 +327,19 @@ export function text(value: string): ContentForm {
 }
 
 /** Content form: a text template (the structurer's `text/` templates) with
- *  `${var}` placeholders substituted from `vars`. */
+ *  `${var}` placeholders substituted from `vars`. When `vars` is a function it
+ *  receives the active {@link RunContext} at resolve time. */
 export function tpl(
   path: string,
-  vars: Record<string, string> | (() => Record<string, string>),
+  vars: Record<string, string> | ((ctx: RunContext) => Record<string, string>),
 ): ContentForm {
   return { kind: "tpl", path, vars };
 }
 
-/** Content form: content computed at run time. The return value is serialised
- *  as JSON / YAML by the target file's extension, or used verbatim if it is
- *  already a string. */
-export function generate(fn: () => unknown): ContentForm {
+/** Content form: content computed at run time from the active
+ *  {@link RunContext}. The return value is serialised as JSON / YAML by the
+ *  target file's extension, or used verbatim if it is already a string. */
+export function generate(fn: (ctx: RunContext) => unknown): ContentForm {
   return { kind: "generate", fn };
 }
 

package/src/structure/engine/content-rules.ts

@@ -13,7 +13,7 @@
 
 import { registerInnerWhenHandler, tryGetActiveRunContext } from "./builders";
 import type { RunContext, Scope } from "./api";
-import type { TriggerContext, TriggerFn } from "./ir";
+import type { ManagedBody, TriggerContext, TriggerFn } from "./ir";
 import {
   deleteAtPath,
   getAtPath,
@@ -163,13 +163,13 @@ export type WithManagedOpts = {
  *  the runner calls this for managed `.json` files. */
 export function withManagedBody(
   obj: JsonObject,
-  body: () => void,
+  body: ManagedBody,
   opts: WithManagedOpts = {},
 ): JsonObject {
   if (active) throw new Error("Nested managed(...) body — engine bug.");
   active = { kind: "json", obj, ctx: opts.ctx, triggerContext: opts.triggerContext };
   try {
-    body();
+    body((opts.ctx ?? opts.triggerContext?.ctx) as RunContext);
     return obj;
   } finally {
     active = undefined;
@@ -189,7 +189,7 @@ export type WithManagedYamlOpts = WithManagedOpts & {
  *  `pnpm-workspace.yaml`); returns the mutated document. Exported for tests. */
 export function withManagedYaml(
   doc: YamlDocument,
-  body: () => void,
+  body: ManagedBody,
   opts: WithManagedYamlOpts = {},
 ): YamlDocument {
   if (active) throw new Error("Nested managed(...) body — engine bug.");
@@ -202,7 +202,7 @@ export function withManagedYaml(
     getDerivedDependencyPin: opts.getDerivedDependencyPin,
   };
   try {
-    body();
+    body((opts.ctx ?? opts.triggerContext?.ctx) as RunContext);
     return doc;
   } finally {
     active = undefined;
@@ -213,7 +213,7 @@ export function withManagedYaml(
  *  (for `.gitignore`); returns the mutated lines. Exported for tests. */
 export function withManagedLines(
   lines: string[],
-  body: () => void,
+  body: ManagedBody,
   opts: WithManagedOpts = {},
 ): string[] {
   if (active) throw new Error("Nested managed(...) body — engine bug.");
@@ -224,7 +224,7 @@ export function withManagedLines(
     triggerContext: opts.triggerContext,
   };
   try {
-    body();
+    body((opts.ctx ?? opts.triggerContext?.ctx) as RunContext);
     return lines;
   } finally {
     active = undefined;

package/src/structure/engine/discovery-fs.ts

@@ -196,7 +196,15 @@ export function discoverRunContext(input: DiscoverInput): RunContext {
       `Could not find a 'block' (or root-as-block) package to derive BlockVars from.`,
     );
   }
-  const blockVars = parseBlockVars(blockMod.name);
+  // This structurer names the block package `<facade>.block`
+  // (block-package-json.ts). The root package carries no `name`, so DISCOVERY
+  // derives BlockVars from the block module — whose `.block` suffix would
+  // otherwise leak into `shortName` on refresh/check (but not init, which is
+  // fed the facade directly). Strip it so `shortName` is the real short name
+  // everywhere. No-op for legacy blocks whose block package IS the bare facade
+  // and for the root-as-block fallback.
+  const facadeName = blockMod.name.replace(/\.block$/, "");
+  const blockVars = parseBlockVars(facadeName);
 
   return createRunContext({
     isSdkInternal,

package/src/structure/engine/ir.ts

@@ -37,21 +37,26 @@ export type TriggerContext = {
 export type TriggerFn = (tctx: TriggerContext) => boolean;
 
 /** Content forms — what to write into a file when creating it.
- *  `tpl.vars` may be a record or a thunk returning a record; the latter
- *  lets rule authors call `blockVars()` lazily at resolve time. */
-export type TplVarsLike = Record<string, string> | (() => Record<string, string>);
+ *  `tpl.vars` and `generate.fn` may be functions; when they are, the
+ *  resolver calls them with the active `RunContext` (the same object
+ *  triggers see as `tctx.ctx`), so lambdas read block identity via their
+ *  argument rather than the module-global `getActiveRunContext()`. */
+export type TplVarsLike = Record<string, string> | ((ctx: RunContext) => Record<string, string>);
 export type ContentForm =
   | { kind: "file"; path: string }
   | { kind: "text"; value: string }
   | { kind: "tpl"; path: string; vars: TplVarsLike }
-  | { kind: "generate"; fn: () => unknown }
+  | { kind: "generate"; fn: (ctx: RunContext) => unknown }
   // A binary static asset (e.g. a logo PNG) copied verbatim from the
   // template tree. Carried as raw bytes, never decoded to a string —
   // only `seed` / `scaffold` consume it (via fs.writeBinary).
   | { kind: "binary"; path: string };
 
-/** Builder-body for a `managed` file (the content-rules lambda). */
-export type ManagedBody = () => void;
+/** Builder-body for a `managed` file (the content-rules lambda). Receives the
+ *  active `RunContext` — the same object triggers see as `tctx.ctx` and that
+ *  `generate`/`tpl` lambdas receive — so the body reads block identity via its
+ *  argument rather than the module-global `getActiveRunContext()`. */
+export type ManagedBody = (ctx: RunContext) => void;
 
 // --- Leaf primitives ---
 

package/src/structure/engine/runner.ts

@@ -110,7 +110,7 @@ function resolveContent(
   form: ContentForm,
   filePath: string,
   templates: TemplateProvider | undefined,
-  isSdkInternal: boolean,
+  ctx: RunContext,
 ): string {
   switch (form.kind) {
     case "text":
@@ -132,15 +132,15 @@ function resolveContent(
         );
       }
       const raw = templates.textRead(form.path);
-      const vars = typeof form.vars === "function" ? form.vars() : form.vars;
+      const vars = typeof form.vars === "function" ? form.vars(ctx) : form.vars;
       return substituteVars(raw, vars);
     }
     case "generate": {
-      const value = form.fn();
+      const value = form.fn(ctx);
       if (filePath.endsWith(".json")) {
         // Resolve `sdk:` sentinels in the generated dep sections so the
         // initial content matches what the body rules re-assert.
-        resolveSdkSentinelsInJson(value, isSdkInternal);
+        resolveSdkSentinelsInJson(value, ctx.isSdkInternal);
         // package.json stays fully expanded (oxfmt's package.json shape);
         // every other .json collapses to oxfmt's generic-file shape.
         return stringifyJson(value, { collapse: !filePath.endsWith("package.json") });
@@ -170,7 +170,7 @@ function writeLeafContent(
   resolvedPath: string,
   form: ContentForm,
   templates: TemplateProvider | undefined,
-  isSdkInternal: boolean,
+  ctx: RunContext,
 ): void {
   if (form.kind === "binary") {
     if (!templates) {
@@ -182,7 +182,7 @@ function writeLeafContent(
     fs.writeBinary(resolvedPath, templates.staticReadBinary(form.path));
     return;
   }
-  fs.write(resolvedPath, resolveContent(form, resolvedPath, templates, isSdkInternal));
+  fs.write(resolvedPath, resolveContent(form, resolvedPath, templates, ctx));
 }
 
 /** Dispatch managed-body parse → mutate → serialize by file extension /
@@ -292,11 +292,11 @@ function applyStructural(
   dryRun: boolean,
   templates: TemplateProvider | undefined,
   initMode: boolean,
-  isSdkInternal: boolean,
+  ctx: RunContext,
 ): Change | undefined {
   const leaf = item.leaf;
   if (leaf.kind === "fixed") {
-    const desired = resolveContent(leaf.content, item.resolvedPath, templates, isSdkInternal);
+    const desired = resolveContent(leaf.content, item.resolvedPath, templates, ctx);
     const exists = fs.exists(item.resolvedPath);
     if (!exists) {
       if (!dryRun) fs.write(item.resolvedPath, desired);
@@ -320,7 +320,7 @@ function applyStructural(
   if (leaf.kind === "scaffold") {
     if (fs.exists(item.resolvedPath)) return undefined;
     if (!dryRun) {
-      writeLeafContent(fs, item.resolvedPath, leaf.initial, templates, isSdkInternal);
+      writeLeafContent(fs, item.resolvedPath, leaf.initial, templates, ctx);
     }
     return {
       scope: item.scope,
@@ -338,7 +338,7 @@ function applyStructural(
     if (!initMode) return undefined;
     if (fs.exists(item.resolvedPath)) return undefined;
     if (!dryRun) {
-      writeLeafContent(fs, item.resolvedPath, leaf.initial, templates, isSdkInternal);
+      writeLeafContent(fs, item.resolvedPath, leaf.initial, templates, ctx);
     }
     return {
       scope: item.scope,
@@ -383,7 +383,7 @@ function applyManaged(
   templates: TemplateProvider | undefined,
   registryLookup: ((packageName: string) => string | undefined) | undefined,
   derivedPinLookup: ((catalogEntry: string) => string | undefined) | undefined,
-  isSdkInternal: boolean,
+  ctx: RunContext,
 ): Change | undefined {
   if (item.leaf.kind !== "managed") return undefined;
   const leaf = item.leaf;
@@ -394,7 +394,7 @@ function applyManaged(
   let created = false;
 
   if (!exists) {
-    beforeRaw = resolveContent(leaf.initial, path, templates, isSdkInternal);
+    beforeRaw = resolveContent(leaf.initial, path, templates, ctx);
     created = true;
   } else {
     beforeRaw = fs.read(path);
@@ -443,7 +443,7 @@ function executePass(
     if (item.leaf.kind === "managed") continue;
     const tctx1 = buildTriggerCtx(snap1, ctx, item.modulePath);
     if (!passesTriggers(item, tctx1)) continue;
-    const change = applyStructural(item, fs, dryRun, templates, initMode, ctx.isSdkInternal);
+    const change = applyStructural(item, fs, dryRun, templates, initMode, ctx);
     if (change) changes.push(change);
   }
 
@@ -462,7 +462,7 @@ function executePass(
       templates,
       registryLookup,
       derivedPinLookup,
-      ctx.isSdkInternal,
+      ctx,
     );
     if (change) changes.push(change);
   }

package/src/structure/rules/block-package-json.ts

@@ -12,7 +12,6 @@ import {
   enforceFieldOrder,
   type RunContext,
 } from "../engine/api";
-import { getActiveRunContext } from "../engine/builders";
 import { findModules, scopeDepMap } from "../engine/ctx";
 import { canonicalPackageJsonOrder } from "./shared/key-order";
 
@@ -111,7 +110,7 @@ export function blockPackageJsonInitial(ctx: RunContext): Record<string, unknown
   };
 }
 
-export function blockPackageJsonRules(): void {
+export function blockPackageJsonRules(ctx: RunContext): void {
   // type:"module" intentionally omitted: the facade's index.js is the
   // CommonJS dev-block descriptor (module.exports / __dirname); ESM would
   // break it. The facade has no TS sources to compile.
@@ -146,7 +145,7 @@ export function blockPackageJsonRules(): void {
   // it in sync on refresh. `block.meta` is deliberately NOT touched here: it
   // is an author-owned seed (set once in the init package.json), so refresh
   // must never overwrite the author's title / description / logo.
-  ensureField("block.components", blockComponents(getActiveRunContext()));
+  ensureField("block.components", blockComponents(ctx));
 
   enforceAlphabeticalOrder("dependencies");
   enforceAlphabeticalOrder("devDependencies");

package/src/structure/rules/block.ts

@@ -2,7 +2,6 @@
 // Workspace-scope deps in the body resolve from ctx.modules.
 
 import { scope, fixed, managed, seed, file, binaryFile, generate } from "../engine/api";
-import { getActiveRunContext } from "../engine/builders";
 import { blockPackageJsonInitial, blockPackageJsonRules } from "./block-package-json";
 
 export function blockRules(): void {
@@ -20,9 +19,9 @@ export function blockRules(): void {
 
     managed(
       "package.json",
-      generate(() => blockPackageJsonInitial(getActiveRunContext())),
-      () => {
-        blockPackageJsonRules();
+      generate((ctx) => blockPackageJsonInitial(ctx)),
+      (ctx) => {
+        blockPackageJsonRules(ctx);
       },
     );
   });

package/src/structure/rules/migrations.ts

@@ -12,7 +12,6 @@
 //    keys/paths). Each line is a one-way decision: every block converges.
 
 import { scope, remove, managed, generate, removeScript, removeDep } from "../engine/api";
-import { getActiveRunContext } from "../engine/builders";
 import { rootPackageJsonInitial } from "./root-package-json";
 
 export function testFrameworkMigration(): void {
@@ -50,7 +49,7 @@ export function legacyCleanup(): void {
     remove(".prettierrc");
     managed(
       "package.json",
-      generate(() => rootPackageJsonInitial(getActiveRunContext())),
+      generate((ctx) => rootPackageJsonInitial(ctx)),
       () => {
         // `pretty` (prettier) is superseded by `fmt` (oxfmt); the standalone
         // deps-updater is now part of block-tools.

package/src/structure/rules/model.ts

@@ -3,7 +3,6 @@
 // (block author owns it).
 
 import { scope, fixed, managed, seed, file, generate, when, whenFilesExist } from "../engine/api";
-import { getActiveRunContext } from "../engine/builders";
 import { modelPackageJsonInitial, modelPackageJsonRules } from "./model-package-json";
 import { COLOCATED_TEST_GLOB } from "./shared/colocated-tests";
 
@@ -32,7 +31,7 @@ export function modelRules(): void {
 
     managed(
       "package.json",
-      generate(() => modelPackageJsonInitial(getActiveRunContext())),
+      generate((ctx) => modelPackageJsonInitial(ctx)),
       () => {
         modelPackageJsonRules();
       },

package/src/structure/rules/root-catalog-bump.ts

@@ -28,7 +28,6 @@ import {
   ensureCatalogVersion,
   pinCatalogToDependencyOf,
 } from "../engine/api";
-import { getActiveRunContext } from "../engine/builders";
 import {
   rootPnpmWorkspaceInitial,
   SDK_CATALOG_PACKAGES,
@@ -53,8 +52,8 @@ export function rootCatalogBumpRules(): void {
           // generator.
           managed(
             "pnpm-workspace.yaml",
-            generate(() => rootPnpmWorkspaceInitial(getActiveRunContext())),
-            () => {
+            generate((ctx) => rootPnpmWorkspaceInitial(ctx)),
+            (ctx) => {
               // SDK families → npm latest, ADD-IF-ABSENT (seeds a migrated
               // block's missing standard keys + overwrites the init
               // placeholder).
@@ -76,7 +75,7 @@ export function rootCatalogBumpRules(): void {
               }
               // The python runenv pin is relevant only to software-bearing
               // blocks; seed it add-if-absent when one is present.
-              if (getActiveRunContext().modules.some((m) => m.scope === "software")) {
+              if (ctx.modules.some((m) => m.scope === "software")) {
                 ensureCatalogVersion(RUNENV_PYTHON, RUNENV_PYTHON_VERSION);
               }
             },

package/src/structure/rules/root-ci.ts

@@ -0,0 +1,55 @@
+// Root-scope CI workflows — the block's GitHub Actions `build.yaml` and
+// `mark-stable.yaml`. Engine-OWNED (`fixed`): rewritten verbatim on every
+// refresh, generated from the block's identity (short name); everything else
+// is a constant baked into the templates.
+//
+// Why fixed, not managed: previously each block carried a hand-copied
+// workflow pinning the shared reusable workflow at `@v4` (a moving branch),
+// so a breaking shared-CI change was absorbed silently and per-block edits
+// drifted. Engine-owning the file makes the pin + job wiring centrally
+// refreshable; the only per-block bits are derived (app-name, slug), so
+// nothing author-tunable is clobbered.
+//
+// Standalone blocks only — `--sdk-internal` blocks (`etc/blocks/*`) carry no
+// per-block workflow (the monorepo owns their CI), hence the
+// `when(!isSdkInternal)` guard, matching the rest of the root scope.
+
+import { scope, when, fixed, tpl } from "../engine/api";
+
+/** Readable default CI label from a short name (`mixcr-clonotyping-2` →
+ *  `Mixcr Clonotyping 2`). Dash/underscore words, title-cased. Human-curated
+ *  casing (e.g. `MiXCR`) is not recoverable from the slug — this is a
+ *  generated label, not the marketing name. */
+function humanizeShortName(shortName: string): string {
+  return shortName
+    .split(/[-_]+/)
+    .filter((w) => w.length > 0)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ");
+}
+
+export function rootCiRules(): void {
+  scope("root", () => {
+    when(
+      ({ ctx }) => !ctx.isSdkInternal,
+      () => {
+        fixed(
+          ".github/workflows/build.yaml",
+          tpl("workflows/build.tpl.yaml", (ctx) => {
+            const shortName = ctx.blockVars.shortName;
+            return {
+              appName: `Block: ${humanizeShortName(shortName)}`,
+              appNameSlug: `block-${shortName}`,
+            };
+          }),
+        );
+        fixed(
+          ".github/workflows/mark-stable.yaml",
+          tpl("workflows/mark-stable.tpl.yaml", (ctx) => ({
+            appName: `Block: ${humanizeShortName(ctx.blockVars.shortName)} - Mark Stable`,
+          })),
+        );
+      },
+    );
+  });
+}

package/src/structure/rules/root.ts

@@ -4,7 +4,6 @@
 // `when(({ ctx }) => !ctx.isSdkInternal, ...)` wrapper.
 
 import { scope, when, fixed, managed, file, generate } from "../engine/api";
-import { getActiveRunContext } from "../engine/builders";
 import { rootPackageJsonInitial, rootPackageJsonRules } from "./root-package-json";
 import { rootPnpmWorkspaceInitial, rootPnpmWorkspaceRules } from "./root-pnpm-workspace";
 import { rootGitignoreRules } from "./root-gitignore";
@@ -19,7 +18,7 @@ export function rootRules(): void {
 
         managed(
           "package.json",
-          generate(() => rootPackageJsonInitial(getActiveRunContext())),
+          generate((ctx) => rootPackageJsonInitial(ctx)),
           () => {
             rootPackageJsonRules();
           },
@@ -27,7 +26,7 @@ export function rootRules(): void {
 
         managed(
           "pnpm-workspace.yaml",
-          generate(() => rootPnpmWorkspaceInitial(getActiveRunContext())),
+          generate((ctx) => rootPnpmWorkspaceInitial(ctx)),
           () => {
             rootPnpmWorkspaceRules();
           },

package/src/structure/rules/software.ts

@@ -6,7 +6,6 @@
 // `init` and never touched again — the block author owns them.
 
 import { scope, managed, seed, generate, text } from "../engine/api";
-import { getActiveRunContext } from "../engine/builders";
 import { softwarePackageJsonInitial, softwarePackageJsonRules } from "./software-package-json";
 
 const MAIN_PY_SEED = `import sys
@@ -24,7 +23,7 @@ export function softwareRules(): void {
 
     managed(
       "package.json",
-      generate(() => softwarePackageJsonInitial(getActiveRunContext())),
+      generate((ctx) => softwarePackageJsonInitial(ctx)),
       () => {
         softwarePackageJsonRules();
       },

package/src/structure/rules/test.ts

@@ -1,7 +1,6 @@
 // Test-scope rules.
 
 import { scope, fixed, managed, scaffold, seed, file, text, generate } from "../engine/api";
-import { getActiveRunContext } from "../engine/builders";
 import { testPackageJsonInitial, testPackageJsonRules } from "./test-package-json";
 
 export function testRules(): void {
@@ -35,7 +34,7 @@ export function testRules(): void {
 
     managed(
       "package.json",
-      generate(() => testPackageJsonInitial(getActiveRunContext())),
+      generate((ctx) => testPackageJsonInitial(ctx)),
       () => {
         testPackageJsonRules();
       },