@plainconceptsplatform/workflows 0.6.1 → 0.16.0

package/dist/index.js

@@ -2,58 +2,68 @@
 import { inspectRepository, parseVisibility, resolveVisibility } from "./repository-inspection.js";
 import { installCatalog, installedRoutes, installTemplate, isTemplateName, removeRouteFiles } from "./catalog-installation.js";
 import { formatCatalog, listCatalog, searchCatalog } from "./catalog-listing.js";
+import { packageVersion } from "./package-baseline.js";
 import { routeNames, templateNames } from "./workflow-catalog.js";
 import { runInteractive } from "./tui.js";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-const HELP_TEXT = `Workflows CLI — install and manage Plain Concepts Platform agentic workflows.
-
-Run with no arguments to launch the interactive TUI, the primary way to select and install
-workflows and templates:
-
-  npx @plainconceptsplatform/workflows
-
-Advanced (non-interactive) commands:
-
-Usage: workflows <command> [options]
-
-Commands:
-  (default)                                   Launch the interactive TUI for selecting and installing items.
-  init                                        Inspect the repository and report its stack and visibility.
-  add [routes] [--template <name>] [--force]  Install route workers, a template, or mandatory files.
-  remove <routes> [--force]                   Uninstall route workers and regenerate the router without them.
-  update                                      Alias for add.
-  status                                      Print repository inspection as JSON.
-  list                                        List all available workflows and templates with install status.
-  search <query>                              Filter workflows and templates by name or description.
-
-Route names (positional arguments to add):
-  refine, implement, triage, apply-review, merge-gate, audit
-
-  add                                         Mandatory files only (opencode.ci.json, compile script,
-                                              shared imports, actions, router, classifier, route matrix).
-  add implement refine direct                Installs those route workers plus mandatory files.
-  add --template agentics-checks             Installs the named template only (no mandatory files).
-  add refine --template agentics-checks      Installs routes + mandatory + the named template.
-  add refine implement --force               Forces re-install of routes plus mandatory, overwriting.
-  remove propose                             Uninstalls the propose worker and drops it from the router.
-
-add and remove keep the router consistent with what is installed: add unions the requested
-routes with the routes already present, and remove drops the requested routes from that set.
-Both regenerate the router, classifier, and route matrix from the resulting set. Changing the
-route set rewrites the package-owned router, so pass --force to overwrite it.
-
-Options:
-  --visibility public|private                 Override repository visibility (init only).
-  --template <name>                           Install a standalone template alongside or instead of routes.
-                                              Templates: agentics-checks, agentics-maintenance,
-                                              app-ci-dotnet-next, app-ci-node-monorepo,
-                                              bug-report, feature-request, github-release,
-                                              opencode.ci.json.
-  --force                                     Overwrite managed files that differ from the package source.
-  -h, --help                                  Show this help text.
-
-Installed workflows are marked [x] when the corresponding .github/workflows/agent-*.md
+const HELP_TEXT = `Workflows CLI — install and update Plain Concepts Platform agentic workflows.
+
+Run with no arguments to launch the interactive TUI, the primary way to select and install
+workflows and templates:
+
+  npx @plainconceptsplatform/workflows
+
+Advanced (non-interactive) commands:
+
+Usage: workflows <command> [options]
+
+Commands:
+  (default)                                   Launch the interactive TUI for selecting and installing items.
+  init                                        Inspect the repository and report its stack and visibility.
+  add [routes] [--template <name>]            Install route workers and refresh every installed package file.
+  update                                      Alias for add: refresh what is installed to this package version.
+  remove <routes>                             Uninstall route workers and regenerate the router without them.
+  status                                      Print repository inspection as JSON.
+  list                                        List all available workflows and templates with install status.
+  search <query>                              Filter workflows and templates by name or description.
+
+Route names (positional arguments to add and remove):
+  ${routeNames.join(", ")}
+
+  add                                         Refresh installed files. In an empty repository: actions, router,
+                                              classifier, matrix, shared imports, opencode.ci.json and the compile
+                                              script, with no workers.
+  add implement refine                        Install those workers on top of the ones already installed.
+  add --template agentics-checks              Install the named template only.
+  add refine --template agentics-checks       Routes plus mandatory files plus the named template.
+  remove audit                                Uninstall the audit worker and drop it from the router.
+
+What an update does to a package-managed file:
+  The file is replaced with this version's, and its ownership header records the version.
+  In a worker (agent-*.md) the env: block at the top is yours: your values are kept, keys the
+  package added arrive with their defaults, keys only you defined stay. When the header records
+  the version you installed from, that release is fetched from npm and a value you never changed
+  follows the package when its default changes. The agent runner pool and the engine gateway URL
+  are kept as well. Everything else in the file is the package's.
+  A file whose ownership header was removed is yours and is left alone unless --force is passed.
+  Templates are yours after installation and are replaced only with --force.
+
+Options:
+  --dry-run                                   Print what add or update would change, write nothing.
+  --force                                     Also overwrite consumer-owned files and changed templates.
+  --baseline <path>                           Use this loops/ directory as the merge baseline instead of
+                                              fetching the installed version from npm. For rolling out a
+                                              version that is not published yet: without a baseline the
+                                              merge is two-way and keeps every consumer value, including
+                                              the package defaults the consumer never chose.
+  --template <name>                           Install a standalone template alongside or instead of routes.
+                                              Templates: ${templateNames.join(", ")}.
+  --visibility public|private                 Override repository visibility (init only).
+  --version                                   Print the package version.
+  -h, --help                                  Show this help text.
+
+Installed workflows are marked [x] when the corresponding .github/workflows/agent-*.md
 file exists relative to the current directory.`;
 export async function run(arguments_, repositoryPath = process.cwd()) {
     const [command, ...options] = arguments_;
@@ -61,6 +71,10 @@ export async function run(arguments_, repositoryPath = process.cwd()) {
         console.log(HELP_TEXT);
         return 0;
     }
+    if (command === "--version" || command === "-v") {
+        console.log(await packageVersion());
+        return 0;
+    }
     if (command === undefined) {
         const force = options.includes("--force");
         return runInteractive(repositoryPath, { force });
@@ -97,32 +111,42 @@ export async function run(arguments_, repositoryPath = process.cwd()) {
         if (parsed.kind === "invalid")
             return fail(parsed.message);
         const inspection = await inspectRepository(repositoryPath);
-        const routes = parsed.routes;
-        const template = parsed.template;
-        const force = parsed.force;
+        const { routes, template, force, dryRun } = parsed;
+        const baseline = localBaseline(parsed.baseline);
         const allConflicts = [];
         const allInstalled = [];
-        if (routes.length > 0) {
+        let catalog;
+        const templatesPlanned = [];
+        // The installed set is always part of the target set: adding a route never drops another,
+        // and a plain update refreshes exactly what is there.
+        if (routes.length > 0 || template === undefined) {
             const selectedRoutes = unionRoutes(routes, await installedRoutes(repositoryPath));
-            const result = await installCatalog(repositoryPath, { force, selectedRoutes, inspection });
-            allConflicts.push(...result.conflicts);
-            allInstalled.push(...result.installed);
-        }
-        else if (template === undefined) {
-            const result = await installCatalog(repositoryPath, { force, selectedRoutes: [], inspection });
-            allConflicts.push(...result.conflicts);
-            allInstalled.push(...result.installed);
+            catalog = await installCatalog(repositoryPath, { force, dryRun, selectedRoutes, inspection, baseline });
+            allConflicts.push(...catalog.conflicts);
+            allInstalled.push(...catalog.installed);
         }
         if (template !== undefined) {
-            const result = await installTemplate(repositoryPath, template, { force, inspection });
-            allConflicts.push(...result.conflicts);
-            allInstalled.push(...result.installed);
+            if (dryRun) {
+                templatesPlanned.push(template);
+            }
+            else {
+                const result = await installTemplate(repositoryPath, template, { force, inspection });
+                allConflicts.push(...result.conflicts);
+                allInstalled.push(...result.installed);
+            }
         }
         if (allConflicts.length > 0 && !force) {
-            console.error(`Catalog conflicts found. Re-run with --force to overwrite package-managed files:\n${allConflicts.join("\n")}`);
+            console.error(`Template conflicts found. Re-run with --force to overwrite consumer-owned copies:\n${allConflicts.join("\n")}`);
             return 1;
         }
-        console.log(JSON.stringify({ command, installed: allInstalled.sort(), conflicts: allConflicts }, null, 2));
+        console.log(JSON.stringify({
+            command,
+            dryRun,
+            ...(catalog === undefined ? {} : summarize(catalog)),
+            ...(templatesPlanned.length > 0 ? { templatesPlanned } : {}),
+            installed: allInstalled.sort(),
+            conflicts: allConflicts,
+        }, null, 2));
         return 0;
     }
     if (command === "remove") {
@@ -136,17 +160,34 @@ export async function run(arguments_, repositoryPath = process.cwd()) {
         const inspection = await inspectRepository(repositoryPath);
         const installed = await installedRoutes(repositoryPath);
         const desiredRoutes = installed.filter((route) => !parsed.routes.includes(route));
-        const result = await installCatalog(repositoryPath, { force: parsed.force, selectedRoutes: desiredRoutes, inspection });
-        if (result.conflicts.length > 0 && !parsed.force) {
-            console.error(`Catalog conflicts found. Re-run with --force to overwrite package-managed files:\n${result.conflicts.join("\n")}`);
-            return 1;
-        }
-        const removed = await removeRouteFiles(repositoryPath, parsed.routes);
-        console.log(JSON.stringify({ command, installed: [...result.installed].sort(), removed, conflicts: result.conflicts }, null, 2));
+        const result = await installCatalog(repositoryPath, { force: parsed.force, dryRun: parsed.dryRun, selectedRoutes: desiredRoutes, inspection, baseline: localBaseline(parsed.baseline) });
+        const removed = parsed.dryRun
+            ? parsed.routes.filter((route) => installed.includes(route)).map((route) => `.github/workflows/agent-${route}.md`)
+            : await removeRouteFiles(repositoryPath, parsed.routes);
+        console.log(JSON.stringify({ command, dryRun: parsed.dryRun, ...summarize(result), installed: [...result.installed].sort(), removed, conflicts: result.conflicts }, null, 2));
         return 0;
     }
     return fail(`Unknown command: ${command}`);
 }
+function summarize(result) {
+    return {
+        packageVersion: result.packageVersion,
+        installedVersions: result.installedVersions,
+        upToDate: result.upToDate,
+        baselines: result.baselines,
+        changes: result.changes.filter((change) => change.status !== "unchanged"),
+        unchanged: result.changes.filter((change) => change.status === "unchanged").length,
+    };
+}
+// A fixed baseline for every recorded version, instead of asking npm. Rolling out a version that
+// is not published yet leaves the merge two-way, which keeps every consumer value, including the
+// package defaults a consumer never chose and would rather have replaced.
+function localBaseline(path) {
+    if (path === undefined)
+        return undefined;
+    const resolved = resolve(path);
+    return async () => resolved;
+}
 function unionRoutes(requested, installed) {
     const result = [...requested];
     for (const route of installed) {
@@ -168,6 +209,8 @@ function parseAddOptions(options) {
     let template;
     let templateSeen = false;
     let force = false;
+    let dryRun = false;
+    let baseline;
     let i = 0;
     while (i < options.length) {
         const token = options[i];
@@ -176,6 +219,18 @@ function parseAddOptions(options) {
             i++;
             continue;
         }
+        if (token === "--dry-run") {
+            dryRun = true;
+            i++;
+            continue;
+        }
+        if (token === "--baseline") {
+            if (i + 1 >= options.length)
+                return invalid("--baseline requires a path.");
+            baseline = options[i + 1];
+            i += 2;
+            continue;
+        }
         if (token === "--template") {
             if (templateSeen)
                 return invalid("--template can only be specified once.");
@@ -202,7 +257,7 @@ function parseAddOptions(options) {
         }
         return invalid(`Unknown route: ${token}. Valid routes: ${routeNames.join(", ")}.`);
     }
-    return { kind: "ok", routes, template, force };
+    return { kind: "ok", routes, template, force, dryRun, baseline };
 }
 function invalid(message) {
     return { kind: "invalid", message };

package/dist/package-baseline.d.ts

@@ -0,0 +1,25 @@
+export declare const PACKAGE_NAME = "@plainconceptsplatform/workflows";
+export declare function packageVersion(): Promise<string>;
+export declare function isValidVersion(version: string): boolean;
+export declare function hasOwnershipHeader(content: string): boolean;
+/** The version recorded in a file's ownership header, or undefined for an unstamped file. */
+export declare function installedVersion(content: string): string | undefined;
+/** Write the version into the ownership header. Re-stamping replaces the previous version. */
+export declare function stampVersion(content: string, version: string): string;
+export type BaselineFetcher = (version: string) => Promise<string | undefined>;
+export interface FetchBaselineOptions {
+    /** Where fetched releases are kept between runs. Defaults to the OS temp directory. */
+    readonly cacheRoot?: string;
+    /** Runs a shell command. Injected by tests. */
+    readonly run?: (command: string) => Promise<void>;
+}
+/**
+ * The `loops/` directory of a published release, or undefined when it cannot be had
+ * (offline, unpublished version). The caller falls back to a two-way merge.
+ */
+export declare function fetchBaseline(version: string, options?: FetchBaselineOptions): Promise<string | undefined>;
+/**
+ * Unpack a gzipped ustar/pax archive (what `npm pack` produces) into a directory. Regular files
+ * and directories only; anything that would escape the destination is skipped.
+ */
+export declare function extractTarball(archive: Buffer, destination: string): void;

package/dist/package-baseline.js

@@ -0,0 +1,138 @@
+// Every installed file carries the package version in its ownership header, stamped at
+// install time. That version is the baseline an update merges against: the CLI fetches that
+// exact release from npm and reads the file as it was when the consumer installed it.
+import { exec as execCallback } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { access, mkdir, readdir, readFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { promisify } from "node:util";
+import { gunzipSync } from "node:zlib";
+const exec = promisify(execCallback);
+export const PACKAGE_NAME = "@plainconceptsplatform/workflows";
+const HEADER = `Managed by ${PACKAGE_NAME}`;
+const VERSION = "\\d+\\.\\d+\\.\\d+(?:-[0-9A-Za-z.-]+)?";
+const STAMPED = new RegExp(`${escapeRegex(HEADER)}@(${VERSION})\\.`);
+const UNSTAMPED = new RegExp(`${escapeRegex(HEADER)}\\.`);
+export async function packageVersion() {
+    const manifest = fileURLToPath(new URL("../package.json", import.meta.url));
+    const { version } = JSON.parse(await readFile(manifest, "utf8"));
+    return version;
+}
+export function isValidVersion(version) {
+    return new RegExp(`^${VERSION}$`).test(version);
+}
+export function hasOwnershipHeader(content) {
+    return content.includes(HEADER);
+}
+/** The version recorded in a file's ownership header, or undefined for an unstamped file. */
+export function installedVersion(content) {
+    return STAMPED.exec(content)?.[1];
+}
+/** Write the version into the ownership header. Re-stamping replaces the previous version. */
+export function stampVersion(content, version) {
+    if (STAMPED.test(content))
+        return content.replace(STAMPED, `${HEADER}@${version}.`);
+    return content.replace(UNSTAMPED, `${HEADER}@${version}.`);
+}
+/**
+ * The `loops/` directory of a published release, or undefined when it cannot be had
+ * (offline, unpublished version). The caller falls back to a two-way merge.
+ */
+export async function fetchBaseline(version, options = {}) {
+    if (!isValidVersion(version))
+        return undefined;
+    const root = options.cacheRoot ?? join(tmpdir(), "plainconceptsplatform-workflows");
+    const directory = join(root, version);
+    const loops = join(directory, "package", "loops");
+    if (await exists(loops))
+        return loops;
+    const run = options.run ?? (async (command) => { await exec(command, { windowsHide: true }); });
+    try {
+        await mkdir(directory, { recursive: true });
+        // npm honours the user's registry configuration, which a direct download would not.
+        let tarball = await findTarball(directory);
+        if (tarball === undefined) {
+            await run(`npm pack "${PACKAGE_NAME}@${version}" --pack-destination "${directory}" --silent`);
+            tarball = await findTarball(directory);
+        }
+        if (tarball === undefined)
+            return undefined;
+        // Extracted here rather than by a `tar` binary: the one on PATH may be GNU tar under
+        // MSYS, which reads `C:\...` as a remote host, or missing altogether.
+        extractTarball(await readFile(join(directory, tarball)), directory);
+        return (await exists(loops)) ? loops : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function findTarball(directory) {
+    return (await readdir(directory)).find((file) => file.endsWith(".tgz"));
+}
+/**
+ * Unpack a gzipped ustar/pax archive (what `npm pack` produces) into a directory. Regular files
+ * and directories only; anything that would escape the destination is skipped.
+ */
+export function extractTarball(archive, destination) {
+    const data = gunzipSync(archive);
+    const field = (block, start, length) => {
+        const raw = block.subarray(start, start + length);
+        const end = raw.indexOf(0);
+        return raw.subarray(0, end === -1 ? raw.length : end).toString("utf8");
+    };
+    let offset = 0;
+    let longName;
+    while (offset + 512 <= data.length) {
+        const header = data.subarray(offset, offset + 512);
+        offset += 512;
+        if (header.every((byte) => byte === 0))
+            break;
+        const size = Number.parseInt(field(header, 124, 12).trim() || "0", 8);
+        const type = field(header, 156, 1) || "0";
+        const body = data.subarray(offset, offset + size);
+        offset += Math.ceil(size / 512) * 512;
+        if (type === "x" || type === "g") {
+            // pax extended header: records of the form "<length> key=value\n"; `path` names the next entry.
+            for (const record of body.toString("utf8").split("\n")) {
+                const match = /^\d+ path=(.*)$/.exec(record);
+                if (match !== null && type === "x")
+                    longName = match[1];
+            }
+            continue;
+        }
+        if (type === "L") {
+            longName = body.toString("utf8").replace(/\0+$/, "");
+            continue;
+        }
+        const prefix = field(header, 345, 155);
+        const shortName = field(header, 0, 100);
+        const name = longName ?? (prefix === "" ? shortName : `${prefix}/${shortName}`);
+        longName = undefined;
+        const parts = name.split("/").filter((part) => part !== "" && part !== ".");
+        if (parts.length === 0 || parts.includes(".."))
+            continue;
+        const target = join(destination, ...parts);
+        if (type === "5") {
+            mkdirSync(target, { recursive: true });
+        }
+        else if (type === "0") {
+            mkdirSync(dirname(target), { recursive: true });
+            writeFileSync(target, body);
+        }
+    }
+}
+async function exists(path) {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/route-processing.d.ts

@@ -1,6 +1,4 @@
 import { type RouteName } from "./workflow-catalog.js";
 export declare function stripRouteFromRouter(yaml: string, route: RouteName): string;
-export declare function stripRouteFromClassifier(shell: string, route: RouteName): string;
-export declare function addRouteExclusion(matrix: string, route: RouteName): string;
 export declare function processRoutes(files: Map<string, string>, selectedRoutes: readonly RouteName[]): Map<string, string>;
 export declare function excludedWorkerFiles(selectedRoutes: readonly RouteName[]): Set<string>;

package/dist/route-processing.js

@@ -1,64 +1,26 @@
 import { routeNames, workflowRoutes } from "./workflow-catalog.js";
+// The router is the one derived file: its content is a function of the installed route set.
+// The classifier stays the complete pure function (a route with no job is a no-op run), and the
+// route matrix reads the installed worker files, so neither is rewritten here.
 const routeCrons = {
     audit: "17 1 * * 1",
 };
+// Deterministic router jobs that exist only to serve one worker route. They leave with it, or
+// the route matrix finds a `route == 'implement'` guard in a router with no implement worker.
+const routeHelperJobs = {
+    implement: ["check-implement-pr"],
+    triage: ["dispatch-triage"],
+};
 export function stripRouteFromRouter(yaml, route) {
     let result = yaml;
     const cron = routeCrons[route];
     if (cron !== undefined) {
         result = result.replace(new RegExp(`^    - cron: "${escapeRegex(cron)}"\\n`, "gm"), "");
     }
-    result = removeJobBlock(result, `call-${route}`);
-    result = result.replace(new RegExp(`^          - ${escapeRegex(route)}\\n`, "gm"), "");
-    return result;
-}
-export function stripRouteFromClassifier(shell, route) {
-    const constName = route.replace(/-/g, "_").toUpperCase() + "_CRON";
-    let result = shell;
-    result = result.replace(new RegExp(`^readonly ${constName}="[^"]*"\\n`, "gm"), "");
-    const cron = routeCrons[route];
-    if (cron !== undefined) {
-        result = result.replace(new RegExp(`\\s*"\\$${constName}"\\) route="${escapeRegex(route)}" ;;\\n`, "g"), "");
-    }
-    result = result.replace(new RegExp(` \\| ${escapeRegex(route)}\\)`, "g"), ")");
-    result = result.replace(new RegExp(`^(\\s+)${escapeRegex(route)} \\| `, "gm"), "$1");
-    if (!result.includes(`| ${route}`) && !result.includes(`${route} |`)) {
-        result = removeAloneDispatchCase(result, route);
-    }
-    return result;
-}
-function removeAloneDispatchCase(shell, route) {
-    const lines = shell.split("\n");
-    const pattern = new RegExp(`^(\\s+)${escapeRegex(route)}\\)\\s*$`);
-    const result = [];
-    let i = 0;
-    while (i < lines.length) {
-        const match = lines[i].match(pattern);
-        if (match) {
-            const indent = match[1];
-            i++;
-            while (i < lines.length) {
-                if (new RegExp(`^${escapeRegex(indent)};;\\s*$`).test(lines[i])) {
-                    i++;
-                    break;
-                }
-                i++;
-            }
-        }
-        else {
-            result.push(lines[i]);
-            i++;
-        }
+    for (const job of [`call-${route}`, ...(routeHelperJobs[route] ?? [])]) {
+        result = removeJobBlock(result, job);
     }
-    return result.join("\n");
-}
-export function addRouteExclusion(matrix, route) {
-    if (matrix.includes(`excluded route '${route}'`))
-        return matrix;
-    let result = matrix;
-    result = result.replace(new RegExp(` ${escapeRegex(route)} `, "g"), " ");
-    const exclusionBlock = `\necho "── Excluded routes ──────────────────────────────────────────────────────"\nif ! grep -q "route == '${route}'" "$ROUTER_YML"; then\n  PASS=$((PASS + 1))\n  echo "  ${route} correctly excluded from work-router.yml"\nelse\n  FAIL=$((FAIL + 1))\n  echo "FAIL: excluded route '${route}' is still in work-router.yml" >&2\nfi\n`;
-    result = result.replace(/(\necho\nif \[ "\$FAIL" -eq 0 \])/, `${exclusionBlock}$1`);
+    result = result.replace(new RegExp(`^          - ${escapeRegex(route)}\\n`, "gm"), "");
     return result;
 }
 export function processRoutes(files, selectedRoutes) {
@@ -66,56 +28,23 @@ export function processRoutes(files, selectedRoutes) {
     if (excludedRoutes.length === 0)
         return files;
     const result = new Map(files);
+    const routerKey = findFileKey(result, "work-router.yml");
+    if (routerKey === undefined)
+        return result;
+    let router = result.get(routerKey);
     for (const route of excludedRoutes) {
-        const routerKey = findFileKey(result, "work-router.yml");
-        if (routerKey !== undefined) {
-            result.set(routerKey, stripRouteFromRouter(result.get(routerKey), route));
-        }
-        const matrixKey = findFileKey(result, "verify-route-matrix.sh");
-        if (matrixKey !== undefined) {
-            result.set(matrixKey, addRouteExclusion(result.get(matrixKey), route));
-        }
-    }
-    const matrixKey = findFileKey(result, "verify-route-matrix.sh");
-    if (matrixKey !== undefined) {
-        result.set(matrixKey, createRouteMatrix(selectedRoutes));
+        router = stripRouteFromRouter(router, route);
     }
+    result.set(routerKey, router);
     return result;
 }
-function createRouteMatrix(selectedRoutes) {
-    const selected = selectedRoutes.join(" ");
-    const excluded = routeNames.filter((route) => !selectedRoutes.includes(route)).join(" ");
-    return `#!/usr/bin/env bash
-set -euo pipefail
-
-HERE="$(cd "$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
-ROUTER_YML="\${HERE}/../../workflows/work-router.yml"
-CLASSIFIER="\${HERE}/../classify-route/classify-route.sh"
-
-bash -n "$CLASSIFIER"
-
-for route in ${selected}; do
-  grep -q "route == '$route'" "$ROUTER_YML" || {
-    echo "FAIL: selected route '$route' has no router job" >&2
-    exit 1
-  }
-done
-
-for route in ${excluded}; do
-  if grep -q "route == '$route'" "$ROUTER_YML"; then
-    echo "FAIL: excluded route '$route' remains in router" >&2
-    exit 1
-  fi
-done
-
-echo "Route matrix: selected routes valid"
-`;
-}
 export function excludedWorkerFiles(selectedRoutes) {
     return new Set(workflowRoutes
         .filter((route) => !selectedRoutes.includes(route.name))
         .map((route) => route.worker));
 }
+// Remove a top-level job (two-space indent) together with the comment lines that introduce it.
+// A job's comment describes that job; left behind it describes nothing.
 function removeJobBlock(yaml, jobName) {
     const lines = yaml.split("\n");
     const startPattern = new RegExp(`^  ${escapeRegex(jobName)}:`);
@@ -129,6 +58,8 @@ function removeJobBlock(yaml, jobName) {
             }
         }
         else if (startPattern.test(line)) {
+            while (result.length > 0 && /^  #/.test(result[result.length - 1]))
+                result.pop();
             skipping = true;
         }
         else {

package/dist/stack-defaults.js

@@ -18,38 +18,44 @@ export function generateStackDefaults(inspection) {
     }
     return { verifyCommands, repoRulesBase, hasDotnet, hasNodeOnly };
 }
+// Only a worker that prints a verification block declares VERIFY_COMMANDS. Adding the key to
+// the others made byte-identical workers read as changed on every update, so a worker without
+// the key is left without it.
 export function injectStackEnv(content, defaults) {
-    let result = content;
-    if (result.includes("VERIFY_COMMANDS:")) {
-        result = result.replace(/  VERIFY_COMMANDS: ".*"/, `  VERIFY_COMMANDS: "${defaults.verifyCommands}"`);
-    }
-    else if (/^env:\n/m.test(result)) {
-        result = result.replace(/^env:\n/m, `env:\n  VERIFY_COMMANDS: "${defaults.verifyCommands}"\n`);
-    }
-    return result;
+    return content.replace(/^  VERIFY_COMMANDS: .*$/m, `  VERIFY_COMMANDS: "${defaults.verifyCommands}"`);
 }
 export function generateOpencodeCi(baseContent, inspection) {
     let result = baseContent;
+    // Idempotent on purpose: this runs on every install and update, and the shared file already
+    // carries some of these steps. A step is added only when no step of that name exists.
     if (inspection.stackHints.solutionFiles.length > 0) {
         const solutionPath = inspection.stackHints.solutionFiles[0].replaceAll("\\", "/");
-        const nugetSteps = `  - name: Cache NuGet packages
+        if (!result.includes("name: Cache NuGet packages")) {
+            const nugetCache = `  - name: Cache NuGet packages
     uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
     with:
       path: ~/.nuget/packages
       key: nuget-\${{ runner.os }}-\${{ hashFiles('**/*.slnx', '**/Directory.Packages.props') }}
       restore-keys: nuget-\${{ runner.os }}-
 
-  - name: Restore .NET dependencies
+`;
+            result = insertBeforeMarker(result, nugetCache, "  - name: Install workspace dependencies");
+        }
+        if (!result.includes("name: Restore .NET dependencies")) {
+            const restore = `  - name: Restore .NET dependencies
     run: dotnet restore ${solutionPath}
+
 `;
-        result = insertBeforeMarker(result, nugetSteps, "  - name: Install workspace dependencies");
+            result = insertBeforeMarker(result, restore, "  - name: Install workspace dependencies");
+        }
     }
-    if (inspection.stackHints.openSpec) {
+    if (inspection.stackHints.openSpec && !result.includes("name: Install OpenSpec CLI")) {
         const openspecStep = `  - name: Install OpenSpec CLI
     run: |
       set -euo pipefail
       npm install -g "@fission-ai/openspec@1.8.0"
       openspec --version
+
 `;
         result = insertBeforeMarker(result, openspecStep, "  - name: Install workspace dependencies");
     }