@natjswenson/shipflow 0.2.6 → 0.3.1

package/lib/detect.mjs

@@ -1,8 +1,8 @@
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { spawnArgs, ghApiJson, git, sha256, readFileCapped } from './gh.mjs';
+import { listPatterns } from './pattern-registry.mjs';
 
-const TEMPLATE_RELATIVE_PATH = '.github/workflows/dev-to-main-automerge.yml';
 const CONFIG_RELATIVE_PATH = '.github/shipflow.json';
 
 // Files/content patterns that indicate branch protection is already managed
@@ -93,8 +93,67 @@ export function listWorkflowJobNames(repoPath, trackedFiles) {
   return [...names].sort();
 }
 
-export function readTemplateFileHash(repoPath) {
-  const full = join(repoPath, TEMPLATE_RELATIVE_PATH);
+const GH_PR_MERGE_AUTO_RE = /gh pr merge --auto/;
+const HEAD_REF_EQ_RE = /head\.ref\s*==/;
+
+// One level finer than listWorkflowJobNames()'s whole-jobs:-section boundary: bounds
+// each INDIVIDUAL job's own line range (its jobNameRe-matching name line down to the
+// next line at that same or lesser indent — the next sibling job, or EOF) so a
+// head.ref == check in one job is never misattributed to a different job's
+// gh pr merge --auto step in the same file.
+export function scanWorkflowShapeSignals(repoPath, trackedFiles) {
+  let restricted = false;
+  let unrestricted = false;
+  for (const f of trackedFiles.filter((f) => /^\.github\/workflows\/.*\.ya?ml$/.test(f))) {
+    const full = join(repoPath, f);
+    if (!existsSync(full)) continue;
+    const lines = readFileCapped(full).split('\n');
+    const jobsLineIdx = lines.findIndex((l) => l.trim() === 'jobs:');
+    if (jobsLineIdx === -1) continue;
+    let i = jobsLineIdx + 1;
+    while (i < lines.length) {
+      // Mirrors listWorkflowJobNames's own dedent-out-of-block termination: a line
+      // that dedents all the way to column 0 ends the WHOLE jobs: section (a
+      // trailing env:/concurrency: block, or EOF), not just the current job — stop
+      // the outer scan entirely rather than treating it as another job candidate.
+      if (lines[i].trim() !== '' && /^\S/.test(lines[i])) break;
+      const nameMatch = lines[i].match(/^\s{2}([\w.-]+):\s*$/);
+      if (!nameMatch) { i++; continue; }
+      const jobStart = i;
+      let jobEnd = lines.length;
+      for (let j = i + 1; j < lines.length; j++) {
+        if (lines[j].trim() === '') continue;
+        if (/^\S/.test(lines[j])) { jobEnd = j; break; }          // dedents to column 0 — end of jobs: section
+        if (lines[j].match(/^\s{2}([\w.-]+):\s*$/)) { jobEnd = j; break; } // next sibling job
+      }
+      const jobBlock = lines.slice(jobStart, jobEnd).join('\n');
+      if (GH_PR_MERGE_AUTO_RE.test(jobBlock)) {
+        if (HEAD_REF_EQ_RE.test(jobBlock)) restricted = true;
+        else unrestricted = true;
+      }
+      i = jobEnd;
+    }
+  }
+  return { hasRestrictedPromotionWorkflow: restricted, hasUnrestrictedAutomergeWorkflow: unrestricted };
+}
+
+export function hasTagsFromMain(repoPath, mainBranch) {
+  const r = git(['tag', '--merged', mainBranch], { cwd: repoPath });
+  return r.status === 0 && r.stdout.trim().length > 0;
+}
+
+export function hasGitflowMarker(repoPath) {
+  if (existsSync(join(repoPath, '.gitflow'))) return true;
+  return git(['config', '--get', 'gitflow.branch.develop'], { cwd: repoPath }).status === 0;
+}
+
+export function listConfiguredRemotes(repoPath) {
+  const r = git(['remote'], { cwd: repoPath });
+  return r.status === 0 ? r.stdout.split('\n').filter(Boolean) : [];
+}
+
+export function readTemplateFileHash(repoPath, targetPath) {
+  const full = join(repoPath, targetPath);
   if (!existsSync(full)) return { exists: false, sha256: null };
   const content = readFileCapped(full);
   return { exists: true, sha256: sha256(content) };
@@ -172,8 +231,18 @@ export function detectRepoState(repoPath, { branches = { main: 'main', dev: 'dev
   const localBranches = branchList.status === 0 ? branchList.stdout.split('\n').filter(Boolean) : [];
 
   const workflowJobNames = listWorkflowJobNames(repoPath, trackedFiles);
-  const templateFiles = { [TEMPLATE_RELATIVE_PATH]: readTemplateFileHash(repoPath) };
+  // Union of every registered pattern's templateTargetPaths — computed unconditionally
+  // with no resolved pattern in hand (there's no config yet on a genuine first run, so
+  // nothing to call resolvePattern(config) with). detect.mjs never imports a
+  // lib/patterns/<id>/index.mjs module directly, only listPatterns() — this is what
+  // keeps "adding a 4th pattern needs no changes to detect.mjs" true in practice.
+  const templateTargetPaths = listPatterns().flatMap((p) => p.templateTargetPaths);
+  const templateFiles = Object.fromEntries(
+    templateTargetPaths.map((path) => [path, readTemplateFileHash(repoPath, path)])
+  );
   const settingsAsCodeArtifact = findSettingsAsCodeArtifact(repoPath, trackedFiles);
+  const { hasRestrictedPromotionWorkflow, hasUnrestrictedAutomergeWorkflow } =
+    scanWorkflowShapeSignals(repoPath, trackedFiles);
 
   const protection = ownerRepo
     ? {
@@ -219,6 +288,11 @@ export function detectRepoState(repoPath, { branches = { main: 'main', dev: 'dev
     repoSettings,
     releasePendingLabelExists,
     stateHash,
+    hasTagsFromMain: hasTagsFromMain(repoPath, branches.main),
+    hasGitflowMarker: hasGitflowMarker(repoPath),
+    configuredRemotes: listConfiguredRemotes(repoPath),
+    hasRestrictedPromotionWorkflow,
+    hasUnrestrictedAutomergeWorkflow,
   };
 }
 

package/lib/pattern-registry.mjs

@@ -0,0 +1,79 @@
+import * as devMainPromotion from './patterns/dev-main-promotion/index.mjs';
+import * as githubFlow from './patterns/github-flow/index.mjs';
+import * as gitflow from './patterns/gitflow/index.mjs';
+
+const PATTERNS = [devMainPromotion, githubFlow, gitflow];
+
+export function listPatterns() {
+  return PATTERNS.map((p) => ({ id: p.id, templateTargetPaths: p.templateTargetPaths }));
+}
+
+export function resolvePattern(config) {
+  const wanted = config?.workflowPattern ?? 'dev-main-promotion';
+  const found = PATTERNS.find((p) => p.id === wanted);
+  if (!found) throw new Error(`resolvePattern: unknown workflowPattern "${wanted}"`);
+  return found;
+}
+
+// Strips a leading '<remote>/' ONLY when it exactly matches one of repoState's
+// configuredRemotes — never a blind "strip to first slash," which would corrupt a
+// purely local release/1.2.0 into 1.2.0. configuredRemotes is populated by
+// detect.mjs (Task 7) via `git remote` — this function takes the already-collected
+// repoState, no git calls of its own, keeping it a pure, easily-testable function.
+function normalizeBranchName(name, remotes) {
+  for (const remote of remotes) {
+    if (name.startsWith(`${remote}/`)) return name.slice(remote.length + 1);
+  }
+  return name;
+}
+
+const DEV_BRANCH_RE = /^(dev|develop|staging)$/;
+const RELEASE_HOTFIX_RE = /^(release|hotfix)\//;
+
+// Computes the 6 shared boolean signals every pattern's detect() consumes. Pure
+// given its single repoState input (matches the contract's scoreAll(repoState)
+// signature — repoPath/git calls stay confined to detect.mjs's collection step,
+// Task 7 — repoState must already carry the raw material (branches,
+// configuredRemotes, tags, .gitflow marker, workflow-shape scan) that step gathers.
+export function computeDetectionSignals(repoState) {
+  const remotes = repoState.configuredRemotes ?? [];
+  const normalized = (repoState.branches?.local ?? []).map((b) => normalizeBranchName(b, remotes));
+  return {
+    hasDevBranch: normalized.some((b) => DEV_BRANCH_RE.test(b)),
+    hasReleaseOrHotfixBranch: normalized.some((b) => RELEASE_HOTFIX_RE.test(b)),
+    hasGitflowMarker: repoState.hasGitflowMarker ?? false,
+    hasRestrictedPromotionWorkflow: repoState.hasRestrictedPromotionWorkflow ?? false,
+    hasUnrestrictedAutomergeWorkflow: repoState.hasUnrestrictedAutomergeWorkflow ?? false,
+    hasTagsFromMain: repoState.hasTagsFromMain ?? false,
+  };
+}
+
+function scoreFromSignals(signals) {
+  return PATTERNS.map((p) => ({ id: p.id, ...p.detect(signals) })).sort((a, b) => b.score - a.score);
+}
+
+export function scoreAll(repoState) {
+  return scoreFromSignals(computeDetectionSignals(repoState));
+}
+// Test-only seam: exercise scoring against a hand-built DetectionSignals object
+// directly, bypassing computeDetectionSignals/repoState entirely. Not part of the
+// public CLI-facing API — the 5 worked-example tests above use this seam because
+// they're testing the SCORING rules in isolation; the two normalization tests
+// above instead call computeDetectionSignals(repoState) directly, since THAT is
+// what those tests are about. Attaching a property to an exported `function`
+// declaration works fine in ESM (the export binding is the function object
+// itself, and function objects are ordinary mutable objects) — this is not the
+// same footgun as trying to reassign a `const`-exported binding from outside the
+// module, which ESM does forbid.
+scoreAll.__scoreFromSignals = scoreFromSignals;
+
+// Confident: top >= 0.7 AND (top - second) > 0.3. Greenfield: top < 0.4. Else
+// Ambiguous — the residual/else branch, no separate condition to satisfy, which is
+// what makes this exhaustive by construction (see design doc's Autodetection section).
+export function classify(ranked) {
+  const [top, second] = ranked;
+  const secondScore = second?.score ?? 0;
+  if (top.score >= 0.7 && top.score - secondScore > 0.3) return 'confident';
+  if (top.score < 0.4) return 'greenfield';
+  return 'ambiguous';
+}

package/lib/patterns/dev-main-promotion/index.mjs

@@ -0,0 +1,49 @@
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mergeMethodToFlag } from '../../render.mjs';
+
+const PATTERN_DIR = dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_SOURCE_PATH = join(
+  PATTERN_DIR, '..', '..', '..', 'templates', 'dev-main-promotion', 'dev-to-main-automerge.yml.tmpl'
+);
+const TARGET_PATH = '.github/workflows/dev-to-main-automerge.yml';
+
+export const id = 'dev-main-promotion';
+export const templateTargetPaths = [TARGET_PATH];
+
+export function protectedBranches(config) {
+  return [config.branches.dev, config.branches.main];
+}
+
+export function templates(config) {
+  return [{
+    id: 'dev-to-main-automerge',
+    targetPath: TARGET_PATH,
+    templateSourcePath: TEMPLATE_SOURCE_PATH,
+    params: {
+      devBranch: config.branches.dev,
+      mainBranch: config.branches.main,
+      mergeFlag: mergeMethodToFlag(config.mergeMethod?.devToMainMethod),
+      releaseCredentialSecret: config.release?.releaseCredential ?? 'GITHUB_TOKEN',
+    },
+  }];
+}
+
+// signals: precomputed DetectionSignals (see pattern-registry.mjs's computeDetectionSignals).
+export function detect(signals) {
+  const evidence = [];
+  let score = 0;
+  if (signals.hasDevBranch && !signals.hasReleaseOrHotfixBranch) {
+    score += 0.5;
+    evidence.push('a dev/develop/staging branch exists with no release/*  or hotfix/*  branches present');
+  }
+  if (signals.hasRestrictedPromotionWorkflow) {
+    score += 0.5;
+    evidence.push('an existing workflow restricts auto-merge-to-main to one specific branch');
+  }
+  return { score, evidence };
+}
+
+export function planEntries(_repoState, _config) {
+  return [];
+}

package/lib/patterns/gitflow/index.mjs

@@ -0,0 +1,55 @@
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mergeMethodToFlag } from '../../render.mjs';
+
+const PATTERN_DIR = dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_DIR = join(PATTERN_DIR, '..', '..', '..', 'templates', 'gitflow');
+
+export const id = 'gitflow';
+export const templateTargetPaths = [
+  '.github/workflows/release-automerge.yml',
+  '.github/workflows/hotfix-automerge.yml',
+  '.github/workflows/hotfix-merge-back.yml',
+  '.github/workflows/release-merge-back.yml',
+];
+
+// release/*  and hotfix/*  are deliberately excluded — transient, cleaned up
+// post-merge like any feature branch under every pattern.
+export function protectedBranches(config) {
+  return [config.branches.dev, config.branches.main];
+}
+
+export function templates(config) {
+  const releasePrefix = config.patternConfig?.gitflow?.releaseBranchPrefix ?? 'release/';
+  const hotfixPrefix = config.patternConfig?.gitflow?.hotfixBranchPrefix ?? 'hotfix/';
+  const baseParams = {
+    devBranch: config.branches.dev,
+    mainBranch: config.branches.main,
+    mergeFlag: mergeMethodToFlag(config.mergeMethod?.devToMainMethod),
+    releaseCredentialSecret: config.release?.releaseCredential ?? 'GITHUB_TOKEN',
+    releaseBranchPrefix: releasePrefix,
+    hotfixBranchPrefix: hotfixPrefix,
+  };
+  return [
+    { id: 'release-automerge', targetPath: '.github/workflows/release-automerge.yml',
+      templateSourcePath: join(TEMPLATE_DIR, 'release-automerge.yml.tmpl'), params: baseParams },
+    { id: 'hotfix-automerge', targetPath: '.github/workflows/hotfix-automerge.yml',
+      templateSourcePath: join(TEMPLATE_DIR, 'hotfix-automerge.yml.tmpl'), params: baseParams },
+    { id: 'hotfix-merge-back', targetPath: '.github/workflows/hotfix-merge-back.yml',
+      templateSourcePath: join(TEMPLATE_DIR, 'hotfix-merge-back.yml.tmpl'), params: baseParams },
+    { id: 'release-merge-back', targetPath: '.github/workflows/release-merge-back.yml',
+      templateSourcePath: join(TEMPLATE_DIR, 'release-merge-back.yml.tmpl'), params: baseParams },
+  ];
+}
+
+export function detect(signals) {
+  const evidence = [];
+  let score = 0;
+  if (signals.hasDevBranch) { score += 0.5; evidence.push('a develop/dev/staging branch exists'); }
+  if (signals.hasReleaseOrHotfixBranch) { score += 0.5; evidence.push('a release/*  or hotfix/*  branch exists'); }
+  // hasGitflowMarker is a best-effort bonus signal only — carries no numeric
+  // weight in v1 (see design doc's Autodetection section).
+  return { score, evidence };
+}
+
+export function planEntries() { return []; }

package/lib/patterns/github-flow/index.mjs

@@ -0,0 +1,43 @@
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mergeMethodToFlag } from '../../render.mjs';
+
+const PATTERN_DIR = dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_SOURCE_PATH = join(PATTERN_DIR, '..', '..', '..', 'templates', 'github-flow', 'main-automerge.yml.tmpl');
+const TARGET_PATH = '.github/workflows/main-automerge.yml';
+
+export const id = 'github-flow';
+export const templateTargetPaths = [TARGET_PATH];
+
+export function protectedBranches(config) {
+  return [config.branches.main];
+}
+
+export function templates(config) {
+  return [{
+    id: 'main-automerge',
+    targetPath: TARGET_PATH,
+    templateSourcePath: TEMPLATE_SOURCE_PATH,
+    params: {
+      mainBranch: config.branches.main,
+      mergeFlag: mergeMethodToFlag(config.mergeMethod?.devToMainMethod),
+      releaseCredentialSecret: config.release?.releaseCredential ?? 'GITHUB_TOKEN',
+    },
+  }];
+}
+
+export function detect(signals) {
+  const evidence = [];
+  let score = 0;
+  if (signals.hasUnrestrictedAutomergeWorkflow || signals.hasTagsFromMain) {
+    score += 0.5;
+    evidence.push('an unrestricted auto-merge-to-main workflow exists, or tags are reachable from main');
+  }
+  if (!signals.hasDevBranch && !signals.hasReleaseOrHotfixBranch) {
+    score += 0.3;
+    evidence.push('no dev/develop/staging branch and no release/*  or hotfix/*  branches exist');
+  }
+  return { score, evidence };
+}
+
+export function planEntries() { return []; }

package/lib/plan.mjs

@@ -1,17 +1,18 @@
-import { renderTemplate, mergeMethodToFlag } from './render.mjs';
+import { resolvePattern } from './pattern-registry.mjs';
+import { renderTemplate } from './render.mjs';
 import { sha256 } from './gh.mjs';
 
-const TEMPLATE_PATH = '.github/workflows/dev-to-main-automerge.yml';
-
 // Pure function — no I/O, no gh/git calls. Diffs repoState (what detect.mjs
 // observed) against config (what the user wants) into a Plan the caller
 // shows to the user before any mutation happens.
-export function computePlan(repoState, config, templateSource) {
+export function computePlan(repoState, config, templateSources) {
+  const pattern = resolvePattern(config);
+  const protectedBranchList = pattern.protectedBranches(config);
   const creates = [];
   const updates = [];
   const noops = [];
 
-  // 1. delete_branch_on_merge repo setting
+  // 1. delete_branch_on_merge — unchanged, repo-wide boolean, no branch names involved.
   const wantDeleteOnMerge = config.branchCleanup?.deleteOnMerge ?? true;
   const haveDeleteOnMerge = repoState.repoSettings?.deleteBranchOnMerge;
   if (haveDeleteOnMerge === wantDeleteOnMerge) {
@@ -24,38 +25,48 @@ export function computePlan(repoState, config, templateSource) {
     });
   }
 
-  // 2. deletion-protecting ruleset — only shipflow's job when it owns protection.
-  // Coarse check (v1 scope): whether *any* ruleset exists at all, not whether
-  // it specifically restricts deletion on the configured branches — apply.mjs
-  // re-checks live state immediately before creating (idempotency guarantee),
-  // so an imprecise plan preview here cannot cause a wrong mutation, only a
-  // possibly-stale preview label.
+  // 2. deletion-ruleset — protects protectedBranchList, not a hardcoded [dev, main].
+  // Description strings below are copied VERBATIM from the pre-existing (single-pattern)
+  // plan.mjs, not rephrased — this repo's own live .github/shipflow.json has
+  // protectionOwner: "external", so the dogfood smoke test
+  // (`node bin/shipflow.js plan --repo .../claude-skills`) exercises this exact else-branch
+  // and must reproduce byte-identical plan-entry text, not just equivalent behavior.
   if (config.protectionOwner === 'shipflow') {
     if ((repoState.rulesets ?? []).length > 0) {
       noops.push({ id: 'deletion-ruleset', description: 'a ruleset already exists (coarse check — see plan.mjs comment)' });
     } else {
-      creates.push({ id: 'deletion-ruleset', description: `create a ruleset protecting ${config.branches.dev}/${config.branches.main} from deletion` });
+      creates.push({ id: 'deletion-ruleset', description: `create a ruleset protecting ${protectedBranchList.join('/')} from deletion` });
     }
   } else {
     noops.push({ id: 'deletion-ruleset', description: `protectionOwner is "${config.protectionOwner}" — deferring to existing mechanism, shipflow installs nothing` });
   }
 
-  // 3. dev-to-main-automerge.yml — content-hash diff against a fresh render,
-  // with hand-edit detection against the last hash shipflow itself recorded.
-  const templateEntry = computeTemplatePlanEntry(repoState, config, templateSource);
-  if (templateEntry.kind === 'noop') noops.push(templateEntry);
-  else if (templateEntry.kind === 'create') creates.push(templateEntry);
-  else updates.push(templateEntry);
+  // 3. per-pattern templates — generalized from one hardcoded entry to N.
+  for (const entry of pattern.templates(config)) {
+    const templateSource = templateSources[entry.id];
+    if (templateSource === undefined) {
+      throw new Error(`computePlan: no templateSources entry for template id "${entry.id}"`);
+    }
+    const planEntry = computeTemplatePlanEntry(repoState, config, entry, templateSource);
+    if (planEntry.kind === 'noop') noops.push(planEntry);
+    else if (planEntry.kind === 'create') creates.push(planEntry);
+    else updates.push(planEntry);
+  }
 
-  // 4. release-pending label — unconditional across every release.mode
-  // (round-6 fix: the labeling job in the template above ships regardless
-  // of mode, so the label must exist regardless of mode too).
+  // 4. release-pending label — unconditional across every release.mode and pattern.
   if (repoState.releasePendingLabelExists) {
     noops.push({ id: 'release-pending-label', description: 'release-pending label already exists' });
   } else {
     creates.push({ id: 'release-pending-label', description: 'create the release-pending label' });
   }
 
+  // 5. pattern-specific entries beyond the 4 common ones above (empty for all 3 v1 patterns).
+  for (const entry of pattern.planEntries(repoState, config)) {
+    if (entry.kind === 'noop') noops.push(entry);
+    else if (entry.kind === 'create') creates.push(entry);
+    else updates.push(entry);
+  }
+
   // liveRequiredChecks: union of classic branch-protection required checks
   // (on the configured main branch) and every fetched ruleset's required
   // checks. v1 scope note: rulesets are unioned without filtering by which
@@ -65,51 +76,46 @@ export function computePlan(repoState, config, templateSource) {
   const rulesetChecks = (repoState.rulesets ?? []).flatMap((rs) => rs.requiredChecks ?? []);
   const liveRequiredChecks = [...new Set([...classicChecks, ...rulesetChecks])].sort();
 
-  return {
-    creates,
-    updates,
-    noops,
-    sourceStateHash: repoState.stateHash,
-    liveRequiredChecks,
-  };
+  return { creates, updates, noops, sourceStateHash: repoState.stateHash, liveRequiredChecks, protectedBranches: protectedBranchList };
 }
 
-function computeTemplatePlanEntry(repoState, config, templateSource) {
-  const params = {
-    devBranch: config.branches.dev,
-    mainBranch: config.branches.main,
-    mergeFlag: mergeMethodToFlag(config.mergeMethod?.devToMainMethod),
-    // Must be a real PAT/App-installation-token secret name, not
-    // "GITHUB_TOKEN" — see the template's header comment for why a
-    // GITHUB_TOKEN-attributed auto-merge never fires the closed-event
-    // label job at all.
-    releaseCredentialSecret: config.release?.releaseCredential ?? 'GITHUB_TOKEN',
-  };
-  const renderedContent = renderTemplate(templateSource, params);
+// entry is one {id, targetPath, templateSourcePath, params} item from
+// pattern.templates(config); templateSource is that entry's already-read-off-disk
+// content (looked up from the caller-supplied templateSources map above).
+//
+// IMPORTANT: the returned plan entry's `id` field is NOT entry.id (the pattern
+// module's own template identifier, e.g. 'release-automerge') — it MUST stay the
+// pre-existing 'template:' + targetPath convention, because apply.mjs's dispatch
+// (`entry.id.startsWith('template:')`) and the empty-required-checks refusal both
+// key off that exact prefix today. Reusing the pattern module's own template id
+// verbatim here would silently break both of those existing mechanisms.
+function computeTemplatePlanEntry(repoState, config, entry, templateSource) {
+  const planId = 'template:' + entry.targetPath;
+  const renderedContent = renderTemplate(templateSource, entry.params);
   const freshHash = sha256(renderedContent);
-  const onDisk = repoState.templateFiles?.[TEMPLATE_PATH];
-  const lastRenderedHash = config.renderedTemplateHashes?.[TEMPLATE_PATH] ?? null;
+  const onDisk = repoState.templateFiles?.[entry.targetPath];
+  const lastRenderedHash = config.renderedTemplateHashes?.[entry.targetPath] ?? null;
 
   if (!onDisk || !onDisk.exists) {
-    return { id: 'template:' + TEMPLATE_PATH, kind: 'create', path: TEMPLATE_PATH, description: `write ${TEMPLATE_PATH}`, renderedHash: freshHash, content: renderedContent };
+    return { id: planId, kind: 'create', path: entry.targetPath, description: `write ${entry.targetPath}`, renderedHash: freshHash, content: renderedContent };
   }
   if (onDisk.sha256 === freshHash) {
-    return { id: 'template:' + TEMPLATE_PATH, kind: 'noop', path: TEMPLATE_PATH, description: `${TEMPLATE_PATH} already matches config` };
+    return { id: planId, kind: 'noop', path: entry.targetPath, description: `${entry.targetPath} already matches config` };
   }
   if (onDisk.sha256 === lastRenderedHash) {
     // On-disk content matches what shipflow itself last rendered, but the
     // config has changed since — a legitimate re-render, not a hand-edit.
-    return { id: 'template:' + TEMPLATE_PATH, kind: 'update', path: TEMPLATE_PATH, description: `re-render ${TEMPLATE_PATH} (config changed)`, renderedHash: freshHash, content: renderedContent, handEditDetected: false };
+    return { id: planId, kind: 'update', path: entry.targetPath, description: `re-render ${entry.targetPath} (config changed)`, renderedHash: freshHash, content: renderedContent, handEditDetected: false };
   }
   // On-disk content matches neither the fresh render nor our last recorded
   // render — someone hand-edited it (or it was never rendered by shipflow).
   // Flagged, not silently overwritten; apply.mjs blocks this entry unless
   // the caller passes an explicit force override naming this entry's id.
   return {
-    id: 'template:' + TEMPLATE_PATH,
+    id: planId,
     kind: 'update',
-    path: TEMPLATE_PATH,
-    description: `${TEMPLATE_PATH} was hand-edited — blocked pending --force`,
+    path: entry.targetPath,
+    description: `${entry.targetPath} was hand-edited — blocked pending --force`,
     renderedHash: freshHash,
     content: renderedContent,
     handEditDetected: true,

package/lib/render.mjs

@@ -35,11 +35,28 @@ const UNSAFE_YAML_STRING_RE = /['\r\n]/;
 // with a digit (case-insensitivity aside, this is the full safe charset).
 const SAFE_SECRET_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
+// Prefix tokens for gitflow's release/*  and hotfix/*  head.ref match guards.
+// These do NOT reuse DEV_BRANCH/MAIN_BRANCH's bare UNSAFE_YAML_STRING_RE check
+// unmodified: those two substitute into an == equality comparison, where an
+// empty string is just a branch name that will never equal anything and so
+// fails CLOSED. These two instead substitute into
+// startsWith(head.ref, '{{...}}') — and EVERY string starts with the empty
+// string, so an empty prefix fails OPEN, collapsing gitflow's release/hotfix-
+// scoped auto-merge into an unrestricted one matching any PR into main. That
+// is the same severity class as the quote-injection Critical finding this
+// module was already hardened against, and it's trivially reachable non-
+// maliciously (a user who wants "no prefix restriction" would naturally try
+// ""). Reject a non-empty-string requirement in addition to the quote/newline
+// check.
+const NON_EMPTY_SAFE_STRING_RE = (v) => v.length > 0 && !UNSAFE_YAML_STRING_RE.test(v);
+
 const TOKEN_VALIDATORS = Object.freeze({
   DEV_BRANCH: (v) => !UNSAFE_YAML_STRING_RE.test(v),
   MAIN_BRANCH: (v) => !UNSAFE_YAML_STRING_RE.test(v),
   MERGE_FLAG: () => true, // closed enum from mergeMethodToFlag — never attacker-shaped
   RELEASE_CREDENTIAL_SECRET: (v) => SAFE_SECRET_NAME_RE.test(v),
+  RELEASE_BRANCH_PREFIX: NON_EMPTY_SAFE_STRING_RE,
+  HOTFIX_BRANCH_PREFIX: NON_EMPTY_SAFE_STRING_RE,
 });
 
 // params: { devBranch, mainBranch, mergeFlag, releaseCredentialSecret }
@@ -53,7 +70,14 @@ export function renderTemplate(templateSource, params) {
   const unsafe = [];
   const rendered = templateSource.replace(TOKEN_RE, (_, name) => {
     const key = TOKEN_TO_PARAM[name];
-    if (!key || !(key in params)) {
+    // A present-but-undefined param counts as MISSING, not as the string
+    // "undefined". `key in params` alone was true for it, so String(undefined)
+    // flowed through as a real value and passed the safety regexes — a config
+    // with no `branches.main` rendered `branches: [undefined]` and
+    // `name: auto-merge dev to undefined`, installing a workflow that could
+    // never fire, with no error at apply time. Found by the rendered-workflow
+    // baseline (tests/baseline.test.mjs) on its first run.
+    if (!key || params[key] === undefined || params[key] === null) {
       missing.push(name);
       return `{{${name}}}`;
     }
@@ -69,7 +93,7 @@ export function renderTemplate(templateSource, params) {
   }
   if (unsafe.length > 0) {
     throw new Error(
-      `renderTemplate: unsafe value for token(s): ${unsafe.join(', ')} — branch names must not contain a quote or newline, and the release-credential secret name must match GitHub's secret-naming rules (letters/digits/underscore, not starting with a digit)`
+      `renderTemplate: unsafe value for token(s): ${unsafe.join(', ')} — branch names and release/hotfix prefixes must be non-empty and must not contain a quote or newline, and the release-credential secret name must match GitHub's secret-naming rules (letters/digits/underscore, not starting with a digit)`
     );
   }
   return rendered;
@@ -80,8 +104,24 @@ const TOKEN_TO_PARAM = Object.freeze({
   MAIN_BRANCH: 'mainBranch',
   MERGE_FLAG: 'mergeFlag',
   RELEASE_CREDENTIAL_SECRET: 'releaseCredentialSecret',
+  RELEASE_BRANCH_PREFIX: 'releaseBranchPrefix',
+  HOTFIX_BRANCH_PREFIX: 'hotfixBranchPrefix',
 });
 
+// INV-MP-12: every TOKEN_TO_PARAM key must have a matching TOKEN_VALIDATORS key, or a
+// substituted value could reach a template with zero validation (the exact class of
+// gap a 2026-07-15 Siege audit found and fixed). Called once at module load against
+// the real exported objects; also independently callable so a unit test can assert
+// the logic itself (not just today's two maps happening to agree) by passing in
+// deliberately-mismatched local fixture objects.
+export function assertTokenValidatorsComplete(tokenToParam, tokenValidators) {
+  const missing = Object.keys(tokenToParam).filter((key) => !(key in tokenValidators));
+  if (missing.length > 0) {
+    throw new Error(`assertTokenValidatorsComplete: TOKEN_VALIDATORS missing entr(y/ies) for: ${missing.join(', ')}`);
+  }
+}
+assertTokenValidatorsComplete(TOKEN_TO_PARAM, TOKEN_VALIDATORS);
+
 export function mergeMethodToFlag(devToMainMethod) {
   switch (devToMainMethod) {
     case 'squash':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@natjswenson/shipflow",
-  "version": "0.2.6",
+  "version": "0.3.1",
   "description": "Scaffold a configurable dev/main branching, auto-merge, branch-cleanup, and release-tagging workflow into any repo",
   "license": "MIT",
   "author": "Nate Swenson",
@@ -41,7 +41,9 @@
   },
   "scripts": {
     "test": "node --test \"tests/**/*.test.mjs\"",
-    "audit": "npm audit --audit-level=moderate"
+    "audit": "npm audit --audit-level=moderate",
+    "prepack": "cp ../../README.md ../../LICENSE ../../CHANGELOG.md .",
+    "postpack": "rm -f README.md LICENSE CHANGELOG.md"
   },
   "devDependencies": {
     "yaml": "^2.9.0"

package/skill-invariants.json

@@ -80,7 +80,26 @@
       "id": "npx-must-pin-latest",
       "pattern": "always with the explicit\\s+`@latest` tag, never bare",
       "rationale": "Self-discovered 2026-07-15 during PAT-wiring dogfood on claude-skills itself: a bare `npx -y @natjswenson/shipflow <command>` silently resolved a stale global install (0.2.0) instead of fetching the current version from the registry, with no warning — meaning every fix through 0.2.5 (including the Critical template-injection fix) was silently skipped. Every CLI invocation in this file must pin @latest."
+    },
+    {
+      "id": "ambiguous-pattern-no-silent-pick",
+      "pattern": "present all 3 (templates|patterns).{0,60}ask the user to choose",
+      "rationale": "Ambiguous/greenfield autodetection must never silently pick a workflow pattern — mirrors the existing protectionOwner disambiguation precedent (ambiguous-protection-owner-prompt)."
     }
   ],
-  "cli_commands_referenced": ["detect", "plan", "apply", "releases", "release-dispatch", "rename-default-branch"]
+  "cli_commands_referenced": ["detect", "plan", "apply", "releases", "release-dispatch", "rename-default-branch"],
+  "_baseline_comment": "Baseline eval sets: deterministic, offline, $0 checks pinned against artifacts from real local runs. These gate `ci / shipflow` alongside the unit tests. Every entry names the test that enforces it so tools/lint_baseline.py can verify the declaration is not aspirational.",
+  "baseline": [
+    {
+      "id": "dogfood-rendered-workflow-golden",
+      "kind": "golden",
+      "test": "tests/baseline.test.mjs",
+      "fixtures": [
+        "evals/baseline/dogfood-shipflow.json",
+        "evals/baseline/dogfood-dev-to-main-automerge.yml"
+      ],
+      "update_command": "node evals/baseline/update.mjs",
+      "rationale": "This monorepo dogfoods shipflow on itself, so .github/shipflow.json and the workflow rendered from it are a genuine input/output pair from a real `apply` run, and that config's renderedTemplateHashes is the receipt shipflow wrote at the time. The baseline re-runs config -> params -> render and asserts byte equality against the frozen golden, that the golden's sha256 still equals the recorded receipt, and that the frozen golden still equals the repo's live committed workflow (so the fixture cannot quietly go stale). Byte-exactness is correct here and nowhere else in the baseline suite: for a workflow file, one changed character is a behavior change to the repo's merge automation. The paired negative assertions (quote injection rejected, missing param throws, merge method actually reaches the output) stop the golden from passing while the validators rot -- the missing-param one found a real bug on its first run: a present-but-undefined param rendered the literal string 'undefined' into `branches: [...]`, installing a workflow that could never fire."
+    }
+  ]
 }