@plainconceptsplatform/workflows 0.6.1 → 0.16.0

package/README.md

@@ -1,88 +1,105 @@
-# Workflows CLI
-
-Install and update shared GitHub Agentic Workflows for Plain Concepts Platform repositories.
-
-## Quick start
-
-The primary entrypoint is the interactive TUI. Run it with no arguments:
-
-```bash
-npx @plainconceptsplatform/workflows
-```
-
-The TUI lists all routes and templates with install status. Arrow keys navigate, space toggles, Enter installs. Selecting routes installs only those route workers plus mandatory files (opencode.ci.json, compile script, shared imports, actions, router, classifier, route matrix). Selecting only templates installs just those templates.
-
-## Install
-
-Before installing workflows, install and configure [`PlainConceptsPlatform/agent-harness`](https://github.com/PlainConceptsPlatform/agent-harness) in the consumer repository. Loop workers invoke the skills and commands it provides. Verify the required skills and commands are available before compiling workflows.
-
-For non-interactive use (advanced):
-
-```bash
-npx @plainconceptsplatform/workflows@latest init
-npx @plainconceptsplatform/workflows@latest add
-npx @plainconceptsplatform/workflows@latest update
-```
-
-For a project-local development dependency:
-
-```bash
-pnpm add -D @plainconceptsplatform/workflows
-pnpm exec workflows              # launch interactive TUI
-pnpm exec workflows init
-pnpm exec workflows add
-```
-
-`init` inspects the repository and reports its stack and visibility. It does not create or manage repository configuration or a manifest.
-
-`add` installs mandatory files (opencode.ci.json, compile script, shared imports, actions, router, classifier, route matrix) when called with no route arguments. Pass route names as positional arguments to install specific route workers alongside the mandatory files:
-
-```bash
-workflows add                        # mandatory files only, no worker .md files
-workflows add implement refine direct  # those route workers plus mandatory files
-workflows add --template agentics-checks  # named template only (no mandatory files)
-workflows add refine --template agentics-checks --force  # routes + template + mandatory, overwriting conflicts
-```
-
-Route names: refine, implement, direct, apply-review, merge-gate, audit, propose. Unknown arguments produce an error.
-
-Use `workflows update --force` to force-overwrite managed files that differ from the package source.
-
-Install optional standalone templates with `add --template`. Available templates are `agentics-checks`, `agentics-maintenance`, `app-ci-dotnet-next`, `app-ci-node-monorepo`, and `github-release`. CI templates are stack-specific copies, not a combined template. `github-release` publishes generated release notes when a `v*` tag is pushed. Edit their top-level `env:` values for repository paths, package names, and commands.
-
-## List and search
-
-List all available workflows, routes, and templates with install status:
-
-```bash
-npx --yes --package @plainconceptsplatform/workflows@latest workflows list
-```
-
-Each entry is marked `[x]` when the corresponding `.github/workflows/agent-*.md` file already exists in the current directory, or `[ ]` when it is not yet installed.
-
-Search by name or description:
-
-```bash
-npx --yes --package @plainconceptsplatform/workflows@latest workflows search "ci"
-```
-
-## Manual installation
-
-The package includes `loops/`, a copyable equivalent of `.github/`:
-
-- `loops/actions/` maps to `.github/actions/`
-- `loops/workflows/` maps to `.github/workflows/`
-- `loops/scripts/` maps to `scripts/`
-
-Copy these files manually if you do not use the CLI. Each worker is self-contained. Edit its
-top-level `env:` defaults directly for consumer-specific endpoint, model, labels, paths, and checks.
-
-## Compile
-
-Consumer repositories generate and commit `*.lock.yml` files:
-
-```bash
-node scripts/compile-agent-workflows.mjs --force
-```
-
-Do not commit generated locks to this package source repository.
+# Workflows CLI
+
+Install and update shared GitHub Agentic Workflows for Plain Concepts Platform repositories.
+
+## Quick start
+
+The primary entrypoint is the interactive TUI. Run it with no arguments:
+
+```bash
+npx @plainconceptsplatform/workflows
+```
+
+The TUI lists all routes and templates with install status. Arrow keys navigate, space toggles, Enter installs. The checked routes are the target set: checking adds a worker, unchecking removes it, and Enter on an unchanged selection refreshes every installed package file to this version. Selecting only templates installs just those templates.
+
+## Install
+
+Before installing workflows, install and configure [`PlainConceptsPlatform/agent-harness`](https://github.com/PlainConceptsPlatform/agent-harness) in the consumer repository. Loop workers invoke the skills and commands it provides. Verify the required skills and commands are available before compiling workflows.
+
+For non-interactive use (advanced):
+
+```bash
+npx @plainconceptsplatform/workflows@latest init
+npx @plainconceptsplatform/workflows@latest add refine implement
+npx @plainconceptsplatform/workflows@latest update --dry-run
+npx @plainconceptsplatform/workflows@latest update
+```
+
+For a project-local development dependency:
+
+```bash
+pnpm add -D @plainconceptsplatform/workflows
+pnpm exec workflows              # launch interactive TUI
+pnpm exec workflows init
+pnpm exec workflows add
+```
+
+`init` inspects the repository and reports its stack and visibility. It does not create or manage repository configuration or a manifest.
+
+`add` installs the mandatory files (opencode.ci.json, compile script, shared imports, actions, router, classifier, route matrix) and the workers named as positional arguments, on top of the workers already installed. With no routes it refreshes what is there:
+
+```bash
+workflows add                              # refresh everything installed; in an empty repository, no workers
+workflows add implement refine             # those workers on top of the installed ones
+workflows add --template agentics-checks   # named template only (no mandatory files)
+workflows add refine --template agentics-checks --force  # routes + template + mandatory; --force also replaces a changed template
+workflows remove audit                     # uninstall the audit worker and drop it from the router
+```
+
+Route names: refine, implement, triage, apply-review, merge-gate, audit, release. Unknown arguments produce an error.
+
+## Update
+
+`update` is `add` with no routes: it refreshes exactly the installed set to this package version. Every package-managed file is replaced and its ownership header records the version it came from:
+
+```
+# Managed by @plainconceptsplatform/workflows@0.7.0. Source: loops/workflows/work-router.yml. ...
+```
+
+The `env:` block at the top of a worker is the repository's and survives: 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 used as the merge baseline, so 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.
+
+- `update --dry-run` prints the plan as JSON and writes nothing.
+- A file whose ownership header was removed is consumer-owned and is skipped unless `--force` is passed.
+- Templates are consumer-owned after installation and are replaced only with `--force`.
+- `--version` prints the package version.
+
+## List and search
+
+List all available workflows, routes, and templates with install status:
+
+```bash
+npx --yes --package @plainconceptsplatform/workflows@latest workflows list
+```
+
+Each entry is marked `[x]` when the corresponding `.github/workflows/agent-*.md` file already exists in the current directory, or `[ ]` when it is not yet installed.
+
+Search by name or description:
+
+```bash
+npx --yes --package @plainconceptsplatform/workflows@latest workflows search "ci"
+```
+
+## Templates
+
+Install optional standalone templates with `add --template`. Available templates are `agentics-checks`, `agentics-maintenance`, `app-ci-dotnet-next`, `app-ci-node-monorepo`, `bug-report`, `feature-request`, `github-release`, and `opencode.ci.json`. CI templates are stack-specific copies, not a combined template. `github-release` publishes generated release notes when a `v*` tag is pushed. Edit their top-level `env:` values for repository paths, package names, and commands.
+
+## Manual installation
+
+The package includes `loops/`, a copyable equivalent of `.github/`:
+
+- `loops/actions/` maps to `.github/actions/`
+- `loops/workflows/` maps to `.github/workflows/`
+- `loops/scripts/` maps to `scripts/`
+
+Copy these files manually if you do not use the CLI. Each worker is self-contained. Edit its
+top-level `env:` defaults directly for consumer-specific endpoint, model, labels, paths, and checks.
+
+## Compile
+
+Consumer repositories generate and commit `*.lock.yml` files:
+
+```bash
+node scripts/compile-agent-workflows.mjs --force
+```
+
+Do not commit generated locks to this package source repository.

package/dist/catalog-installation.d.ts

@@ -1,15 +1,49 @@
 import { type RouteName, type TemplateName } from "./workflow-catalog.js";
+import { type BaselineFetcher } from "./package-baseline.js";
 import type { RepositoryInspection } from "./repository-inspection.js";
+export type ChangeStatus = "added" | "updated" | "unchanged" | "skipped" | "removed";
+export interface FileChange {
+    readonly target: string;
+    readonly status: ChangeStatus;
+    /** Why a file was skipped. */
+    readonly reason?: string;
+    /** Version the consumer's copy was installed from, when its header records one. */
+    readonly installedVersion?: string;
+    readonly keptEnv?: readonly string[];
+    readonly updatedDefaults?: readonly string[];
+    readonly consumerOnlyEnv?: readonly string[];
+    readonly droppedEnv?: readonly string[];
+}
+export interface BaselineStatus {
+    readonly version: string;
+    readonly status: "used" | "unavailable";
+}
 export interface CatalogInstallResult {
+    /** Every package-managed target in the installed set, whether it changed or not. */
     readonly installed: readonly string[];
+    /** Consumer-owned files that differ and were not overwritten. Only templates report these. */
     readonly conflicts: readonly string[];
+    readonly changes: readonly FileChange[];
+    readonly packageVersion: string;
+    /** Versions found in the consumer's ownership headers before this run. */
+    readonly installedVersions: readonly string[];
+    readonly baselines: readonly BaselineStatus[];
+    readonly upToDate: boolean;
+    readonly dryRun: boolean;
 }
 export interface CatalogInstallOptions {
+    /** Also overwrite files whose ownership header was removed, and changed templates. */
     readonly force?: boolean;
     readonly sourcePath?: string;
     readonly selectedRoutes?: readonly RouteName[];
     readonly inspection?: RepositoryInspection;
     readonly compile?: (repositoryPath: string) => Promise<void>;
+    /** Compute the plan and write nothing. */
+    readonly dryRun?: boolean;
+    /** Where the baseline release comes from. Defaults to npm. */
+    readonly baseline?: BaselineFetcher;
+    /** The version stamped into headers. Defaults to this package's. */
+    readonly packageVersion?: string;
 }
 interface CatalogFile {
     readonly source: string;
@@ -19,8 +53,11 @@ interface CatalogFile {
 export declare function mandatoryFileSpecs(sourcePath: string): CatalogFile[];
 export declare function catalogSourcePath(modulePath?: string): string;
 export declare function installCatalog(repositoryPath: string, options?: CatalogInstallOptions): Promise<CatalogInstallResult>;
-export declare function installTemplate(repositoryPath: string, template: TemplateName, options?: CatalogInstallOptions): Promise<CatalogInstallResult>;
-export declare function installMandatoryFiles(repositoryPath: string, options?: CatalogInstallOptions): Promise<CatalogInstallResult>;
+export interface TemplateInstallResult {
+    readonly installed: readonly string[];
+    readonly conflicts: readonly string[];
+}
+export declare function installTemplate(repositoryPath: string, template: TemplateName, options?: Pick<CatalogInstallOptions, "force" | "sourcePath" | "inspection">): Promise<TemplateInstallResult>;
 export declare function installedRoutes(repositoryPath: string): Promise<RouteName[]>;
 export declare function removeRouteFiles(repositoryPath: string, routes: readonly RouteName[]): Promise<string[]>;
 export declare function isTemplateName(value: string): value is TemplateName;

package/dist/catalog-installation.js

@@ -8,6 +8,8 @@ import { parse as parseYaml } from "yaml";
 import { catalogTemplates, mandatoryFiles, routeNames, templateNames, workflowRoutes } from "./workflow-catalog.js";
 import { processRoutes, excludedWorkerFiles } from "./route-processing.js";
 import { generateOpencodeCi, generateOpencodeConfig, generateStackDefaults, injectStackEnv } from "./stack-defaults.js";
+import { mergeRouter, mergeWorker } from "./worker-env.js";
+import { fetchBaseline, hasOwnershipHeader, installedVersion, packageVersion, stampVersion } from "./package-baseline.js";
 const execFileAsync = promisify(execFile);
 const sourceMappings = [
     ["actions", ".github/actions"],
@@ -24,116 +26,187 @@ export function mandatoryFileSpecs(sourcePath) {
 export function catalogSourcePath(modulePath = fileURLToPath(import.meta.url)) {
     return resolve(dirname(modulePath), "..", "loops");
 }
+const isWorker = (target) => target.startsWith(".github/workflows/agent-") && target.endsWith(".md");
+const isRouter = (target) => target === ".github/workflows/work-router.yml";
+const carriesHeader = (target) => /\.(ya?ml|md|sh|mjs|cjs)$/.test(target);
+const normalizeEol = (text) => text.replaceAll("\r\n", "\n");
 export async function installCatalog(repositoryPath, options = {}) {
+    const version = options.packageVersion ?? await packageVersion();
     const sourcePath = options.sourcePath ?? catalogSourcePath();
     const selectedRoutes = options.selectedRoutes ?? routeNames;
     const allFiles = [...await catalogFiles(sourcePath), ...mandatoryFileSpecs(sourcePath)];
     const deduplicated = allFiles.filter((file, index) => allFiles.findIndex((f) => f.target === file.target) === index).sort((left, right) => left.target.localeCompare(right.target));
     const excluded = excludedWorkerFiles(selectedRoutes);
-    const filtered = deduplicated.filter((file) => {
-        const fileName = file.target.split("/").pop() ?? "";
-        return !excluded.has(fileName);
-    });
-    const fileContents = new Map();
+    const filtered = deduplicated.filter((file) => !excluded.has(file.target.split("/").pop() ?? ""));
+    const packageContents = new Map();
     for (const file of filtered) {
-        fileContents.set(file.target, await readFile(file.source, "utf8"));
+        packageContents.set(file.target, normalizeEol(await readFile(file.source, "utf8")));
+    }
+    let processed = processRoutes(packageContents, selectedRoutes);
+    // Read and write LF, always. Every one of these files ends up on a Linux runner, the package
+    // and every consumer declare `* text=auto eol=lf`, and a shell script with CRLF fails on its
+    // shebang. Preserving whatever a file happened to have instead only carried legacy CRLF
+    // forward, which git then reported as needing normalisation on every later commit.
+    const existing = new Map();
+    for (const target of processed.keys()) {
+        const path = join(repositoryPath, target);
+        if (!await exists(path))
+            continue;
+        existing.set(target, normalizeEol(await readFile(path, "utf8")));
     }
-    let processedContents = processRoutes(fileContents, selectedRoutes);
     if (options.inspection !== undefined) {
-        const defaults = generateStackDefaults(options.inspection);
-        processedContents = injectStackIntoWorkers(processedContents, defaults);
-        processedContents = transformOpencodeFiles(processedContents, options.inspection);
+        processed = applyStackDefaults(processed, options.inspection, existing);
     }
-    processedContents = await preserveConsumerWorkerEnv(repositoryPath, processedContents);
-    const updates = [...processedContents.entries()]
-        .filter(([target]) => filtered.find((file) => file.target === target)?.managed ?? true)
-        .map(([target, content]) => ({ target, content }));
-    const conflicts = await conflictingTargets(repositoryPath, updates);
-    if (conflicts.length > 0 && !options.force)
-        return { installed: [], conflicts };
-    const stagedLocks = await validateStagedCatalog(repositoryPath, updates, options.compile);
-    await applyTransaction(repositoryPath, [...updates, ...stagedLocks, await preCommitHookUpdate(repositoryPath)]);
-    return { installed: [...processedContents.keys()].sort(), conflicts };
-}
-function injectStackIntoWorkers(files, defaults) {
-    const result = new Map(files);
-    for (const [key, content] of result) {
-        if (key.startsWith(".github/workflows/agent-") && key.endsWith(".md")) {
-            result.set(key, injectStackEnv(content, defaults));
+    const fetcher = options.baseline ?? fetchBaseline;
+    const baselineDirectories = new Map();
+    const baselineFor = (installed) => {
+        let pending = baselineDirectories.get(installed);
+        if (pending === undefined) {
+            pending = fetcher(installed);
+            baselineDirectories.set(installed, pending);
+        }
+        return pending;
+    };
+    const changes = [];
+    const updates = [];
+    const installedVersions = new Set();
+    for (const [target, packageText] of processed) {
+        const current = existing.get(target);
+        let text = packageText;
+        let change = { target, status: "added" };
+        if (current !== undefined) {
+            const recorded = carriesHeader(target) ? installedVersion(current) : undefined;
+            if (recorded !== undefined)
+                installedVersions.add(recorded);
+            if (isWorker(target) || isRouter(target)) {
+                const baselineText = recorded === undefined ? undefined : await baselineSource(await baselineFor(recorded), target);
+                const merge = isRouter(target) ? mergeRouter : mergeWorker;
+                const merged = merge(packageText, current, baselineText);
+                text = merged.content;
+                change = {
+                    target,
+                    status: "updated",
+                    ...(recorded === undefined ? {} : { installedVersion: recorded }),
+                    ...(merged.report.keptEnv.length > 0 ? { keptEnv: merged.report.keptEnv } : {}),
+                    ...(merged.report.updatedDefaults.length > 0 ? { updatedDefaults: merged.report.updatedDefaults } : {}),
+                    ...(merged.report.consumerOnlyEnv.length > 0 ? { consumerOnlyEnv: merged.report.consumerOnlyEnv } : {}),
+                    ...(merged.report.droppedEnv.length > 0 ? { droppedEnv: merged.report.droppedEnv } : {}),
+                };
+            }
+            else {
+                change = { target, status: "updated", ...(recorded === undefined ? {} : { installedVersion: recorded }) };
+            }
+        }
+        text = stampVersion(text, version);
+        if (current !== undefined && text === current) {
+            change = { ...change, status: "unchanged" };
         }
+        else if (current !== undefined && carriesHeader(target) && !hasOwnershipHeader(current) && !options.force) {
+            // Removing the ownership header is how a consumer takes a file over.
+            change = { target, status: "skipped", reason: "consumer-owned: the ownership header was removed; pass --force to reclaim it" };
+        }
+        else {
+            updates.push({ target, content: text });
+        }
+        changes.push(change);
+    }
+    const removals = await orphanedManagedFiles(repositoryPath, new Set(processed.keys()));
+    for (const target of removals)
+        changes.push({ target, status: "removed" });
+    const baselines = [];
+    for (const [requested, pending] of baselineDirectories) {
+        baselines.push({ version: requested, status: (await pending) === undefined ? "unavailable" : "used" });
+    }
+    const result = {
+        installed: [...processed.keys()].sort(),
+        conflicts: [],
+        changes,
+        packageVersion: version,
+        installedVersions: [...installedVersions].sort(),
+        baselines,
+        upToDate: updates.length === 0 && removals.length === 0,
+        dryRun: options.dryRun ?? false,
+    };
+    if (options.dryRun)
+        return result;
+    // Deletions go first: a pruned action must be gone before the compile reads the tree, or a
+    // worker still referencing it would compile against a file that is about to disappear.
+    await removeFiles(repositoryPath, removals);
+    if (updates.length > 0) {
+        const stagedLocks = await validateStagedCatalog(repositoryPath, updates, options.compile);
+        await applyTransaction(repositoryPath, [...updates, ...stagedLocks, await preCommitHookUpdate(repositoryPath)]);
+    }
+    else {
+        await applyTransaction(repositoryPath, [await preCommitHookUpdate(repositoryPath)]);
     }
     return result;
 }
-async function preserveConsumerWorkerEnv(repositoryPath, files) {
+// Stack defaults are derived from the repository, not chosen by a person, so the derived files
+// (the shared CI setup and the OpenCode config) get them on every run and stay stable. A worker
+// gets its VERIFY_COMMANDS default once, when it is first installed: after that the value is the
+// consumer's, and the env merge keeps it.
+function applyStackDefaults(files, inspection, existing) {
+    const defaults = generateStackDefaults(inspection);
     const result = new Map(files);
     for (const [target, content] of result) {
-        if (!target.startsWith(".github/workflows/agent-") || !target.endsWith(".md"))
-            continue;
-        const existingPath = join(repositoryPath, target);
-        if (!await exists(existingPath))
-            continue;
-        result.set(target, mergeWorkerEnv(content, await readFile(existingPath, "utf8")));
+        if (isWorker(target) && !existing.has(target)) {
+            result.set(target, injectStackEnv(content, defaults));
+        }
+        else if (target.endsWith("opencode-ci.md")) {
+            result.set(target, generateOpencodeCi(content, inspection));
+        }
+        else if (target === "opencode.ci.json") {
+            result.set(target, generateOpencodeConfig(content, inspection));
+        }
     }
     return result;
 }
-function mergeWorkerEnv(packageContent, consumerContent) {
-    const consumerEnv = workerEnvValues(consumerContent);
-    let result = packageContent.replace(/^  ([A-Z][A-Z0-9_]*): .+$/gm, (line, key) => consumerEnv.has(key) ? `  ${key}: ${consumerEnv.get(key)}` : line);
-    const endpoint = engineEndpoint(consumerContent);
-    if (endpoint !== undefined) {
-        result = result.replace(/^    OPENAI_BASE_URL: .+$/m, `    OPENAI_BASE_URL: ${endpoint}`);
-    }
-    return preserveRunnerPool(result, consumerContent);
-}
-// Which self-hosted pool a worker's agent jobs run on. gh-aw cannot share runs-on through
-// an import, so every worker names it, and it belongs with the env values rather than with
-// the prompt: a forced update that rewrote it would move a repository's agents onto another
-// pool, and one of ours has two machines in it. ubuntu-latest is excluded, being GitHub's
-// own runner, used by the deterministic jobs everywhere and chosen by nobody.
-function runnerPools(content) {
-    const found = new Set();
-    for (const match of content.matchAll(/^\s*runs-on(?:-slim)?: (\S+)\s*$/gm)) {
-        if (match[1] !== "ubuntu-latest")
-            found.add(match[1]);
-    }
-    return [...found];
-}
-function preserveRunnerPool(packageContent, consumerContent) {
-    const mine = runnerPools(consumerContent);
-    const theirs = runnerPools(packageContent);
-    // Only an unambiguous swap. A consumer naming several pools has drifted rather than
-    // decided, and guessing which it meant is worse than leaving the package's.
-    if (mine.length !== 1 || theirs.length !== 1 || mine[0] === theirs[0])
-        return packageContent;
-    return packageContent.replace(/^(\s*runs-on(?:-slim)?: )(\S+)(\s*)$/gm, (line, prefix, pool, tail) => pool === "ubuntu-latest" ? line : `${prefix}${mine[0]}${tail}`);
-}
-function workerEnvValues(content) {
-    const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/m.exec(content)?.[1];
-    const envBlock = frontmatter === undefined ? undefined : /^env:\r?\n((?:  .*\r?\n?)*)/m.exec(frontmatter)?.[1];
-    const values = new Map();
-    if (envBlock === undefined)
-        return values;
-    for (const line of envBlock.split(/\r?\n/)) {
-        const match = /^  ([A-Z][A-Z0-9_]*): (.+)$/.exec(line);
-        if (match !== null)
-            values.set(match[1], match[2]);
+// Directories that belong wholly to the package. A file here that carries our ownership header
+// and is no longer in the package was deleted upstream, and without this it would sit in every
+// consumer forever: that is how `stale-recovery` and `update-changelog` outlived the code that
+// called them. Deliberately not `.github/workflows/`, where a worker's absence means the route
+// is not installed rather than gone, and never anything without a header, which is a fork.
+const pruneRoots = [".github/actions", ".github/workflows/shared"];
+async function orphanedManagedFiles(repositoryPath, keep) {
+    const orphans = [];
+    for (const root of pruneRoots) {
+        const directory = join(repositoryPath, root);
+        if (!await exists(directory))
+            continue;
+        for (const file of await filesIn(directory)) {
+            const target = `${root}/${file.replaceAll("\\", "/")}`;
+            if (keep.has(target))
+                continue;
+            if (!carriesHeader(target) && !target.endsWith(".cjs") && !target.endsWith(".js"))
+                continue;
+            const content = await readFile(join(directory, file), "utf8");
+            if (hasOwnershipHeader(content))
+                orphans.push(target);
+        }
     }
-    return values;
+    return orphans.sort();
 }
-function engineEndpoint(content) {
-    return /^    OPENAI_BASE_URL: (.+)$/m.exec(content)?.[1];
-}
-function transformOpencodeFiles(files, inspection) {
-    const result = new Map(files);
-    for (const [key, content] of result) {
-        if (key.endsWith("opencode-ci.md")) {
-            result.set(key, generateOpencodeCi(content, inspection));
+async function removeFiles(repositoryPath, targets) {
+    for (const target of targets) {
+        await rm(join(repositoryPath, target), { force: true });
+        // An action is a directory with one manifest in it; leaving the empty shell behind is litter.
+        const directory = dirname(join(repositoryPath, target));
+        try {
+            if ((await readdir(directory)).length === 0)
+                await rm(directory, { recursive: true, force: true });
         }
-        else if (key === "opencode.ci.json") {
-            result.set(key, generateOpencodeConfig(content, inspection));
+        catch {
+            // the directory is gone or not empty, either of which is fine
         }
     }
-    return result;
+}
+async function baselineSource(loops, target) {
+    if (loops === undefined)
+        return undefined;
+    const path = join(loops, "workflows", target.slice(".github/workflows/".length));
+    if (!await exists(path))
+        return undefined;
+    return normalizeEol(await readFile(path, "utf8"));
 }
 // Templates that need a companion config beside the workflow file. actionlint only
 // knows GitHub-hosted runner labels, so every workflow naming a self-hosted label is an
@@ -180,19 +253,6 @@ export async function installTemplate(repositoryPath, template, options = {}) {
     }
     return { installed: (await Promise.all(destinations.map(async (entry) => await exists(entry.source) ? entry.target : undefined))).filter((file) => file !== undefined), conflicts };
 }
-export async function installMandatoryFiles(repositoryPath, options = {}) {
-    const sourcePath = options.sourcePath ?? catalogSourcePath();
-    const files = mandatoryFileSpecs(sourcePath).sort((left, right) => left.target.localeCompare(right.target));
-    const conflicts = (await Promise.all(files.map(async (file) => {
-        const destination = join(repositoryPath, file.target);
-        return await exists(destination) && !(await filesMatch(file.source, destination)) ? file.target : undefined;
-    }))).filter((file) => file !== undefined);
-    if (conflicts.length > 0 && !options.force)
-        return { installed: [], conflicts };
-    const updates = await Promise.all(files.map(async (file) => ({ target: file.target, content: await readFile(file.source, "utf8") })));
-    await applyTransaction(repositoryPath, [...updates, await preCommitHookUpdate(repositoryPath)]);
-    return { installed: files.map((file) => file.target), conflicts };
-}
 export async function installedRoutes(repositoryPath) {
     const found = await Promise.all(workflowRoutes.map(async (route) => (await exists(join(repositoryPath, ".github", "workflows", route.worker))) ? route.name : undefined));
     return found.filter((name) => name !== undefined);
@@ -253,15 +313,6 @@ export async function runCompileIfAvailable(repositoryPath) {
         await execFileAsync("node", [script, "--force"], { cwd: repositoryPath });
     }
 }
-async function conflictingTargets(repositoryPath, updates) {
-    const conflicts = (await Promise.all(updates.map(async ({ target, content }) => {
-        const destination = join(repositoryPath, target);
-        if (!await exists(destination))
-            return undefined;
-        return (await readFile(destination, "utf8")) === content ? undefined : target;
-    }))).filter((target) => target !== undefined);
-    return [...new Set(conflicts)].sort();
-}
 async function validateStagedCatalog(repositoryPath, updates, compileOverride) {
     const temporaryRoot = join(repositoryPath, ".opencode", ".tmp");
     await mkdir(temporaryRoot, { recursive: true });
@@ -280,10 +331,17 @@ async function validateStagedCatalog(repositoryPath, updates, compileOverride) {
         await rm(stagingPath, { force: true, recursive: true });
     }
 }
+// The compile needs the workflows and the compile script. An update that changes neither still
+// recompiles against the consumer's current copies, so both come along.
 async function copyCompilationInputs(repositoryPath, stagingPath) {
     const githubPath = join(repositoryPath, ".github");
     if (await exists(githubPath))
         await cp(githubPath, join(stagingPath, ".github"), { recursive: true });
+    const script = join(repositoryPath, "scripts", "compile-agent-workflows.mjs");
+    if (await exists(script)) {
+        await mkdir(join(stagingPath, "scripts"), { recursive: true });
+        await copyFile(script, join(stagingPath, "scripts", "compile-agent-workflows.mjs"));
+    }
 }
 async function initializeStagingRepository(stagingPath) {
     await execFileAsync("git", ["init", "--quiet"], { cwd: stagingPath, windowsHide: true });
@@ -369,7 +427,10 @@ function catalogTemplateMeta(template) {
     const entry = catalogTemplates.find((item) => item.name === template);
     if (entry === undefined)
         throw new Error(`Unknown template: ${template}`);
-    const directory = template.startsWith("opencode") ? "opencode" : template.startsWith("app-ci-") ? "ci" : template === "github-release" ? "release" : template === "visual-evidence" ? "visual-evidence" : template === "bug-report" || template === "feature-request" ? "issues" : "agentics";
+    // The directory is a field on the entry now. It used to be inferred from the name by a chain
+    // of ternaries ending in "agentics", so a new template in any other directory installed the
+    // wrong file or none at all, and the default hid it.
+    const directory = entry.directory ?? (template.startsWith("opencode") ? "opencode" : template.startsWith("app-ci-") ? "ci" : template === "github-release" ? "release" : template === "bug-report" || template === "feature-request" ? "issues" : "agentics");
     const isWorkflow = entry.file.endsWith(".yml");
     const inferredTarget = template === "app-ci-dotnet-next"
         ? ".github/workflows/app-ci.yml"
@@ -380,6 +441,8 @@ function catalogTemplateMeta(template) {
 async function catalogFiles(sourcePath) {
     const files = [];
     for (const [sourceDirectory, targetDirectory] of sourceMappings) {
+        if (!await exists(join(sourcePath, sourceDirectory)))
+            continue;
         for (const file of await filesIn(join(sourcePath, sourceDirectory))) {
             if (isGeneratedFile(file))
                 continue;