delivery-friction-analyzer 0.3.0 → 0.5.0

package/README.md

@@ -50,7 +50,7 @@ For a guided first run in a local terminal, use the opt-in interactive flow:
 npm run analyze:github -- --interactive
 ```
 
-Interactive mode asks for the same run choices supported by flags, including repository, PR limit, profile path, output directory, dry-run mode, CSV exports, JSON completion output, and configured PR class exclusions. Scripted and CI usage should keep passing explicit flags; missing required flags without `--interactive` fail deterministically instead of waiting for input.
+Interactive mode asks for the same run choices supported by flags, including repository, PR limit, profile path, output directory, dry-run mode, CSV exports, JSON completion output, and configured PR class exclusions. It can also create a missing repository profile path or write a generated profile copy with confirmed workflow context and release PR title rules. Scripted and CI usage should keep passing explicit flags; missing required flags without `--interactive` fail deterministically instead of waiting for input.
 
 ## Repository Profiles
 
@@ -61,7 +61,8 @@ Profiles can define:
 - file categories such as code, tests, docs, generated files, infrastructure, or config;
 - file roles such as core product code, release notes, fixtures, planning docs, or generated docs;
 - functional surfaces such as runtime, test suite, release notes, or user docs;
-- PR classes such as release, dependency, feature, or other repository-specific groups.
+- PR classes such as release, dependency, feature, or other repository-specific groups;
+- workflow context such as merge method, release strategy, and branch strategy.
 
 Use `fixtures/github/mcp-writing/profile.json` as a starting point, then save a copy for the repository you want to analyze. The full profile format is documented in `docs/reference/repository-profile.md`, and the schema lives at `schemas/repository-profile.schema.json`.
 

package/docs/reference/repository-profile.md

@@ -53,3 +53,33 @@ If both matchers are present on one rule, both must match. If no rule matches, t
 ```
 
 Class identifiers are validated as lower-kebab-case or lower_snake_case strings. Profile validation rejects duplicate PR class rule IDs, empty match objects, invalid class identifiers, and invalid title regexes.
+
+Interactive setup can add a release PR class rule from a confirmed title convention using the current title-only matcher shape. Branch strategy answers stay in `workflow` context only; they do not create branch-based PR class matching.
+
+## Workflow Context
+
+`workflow` is optional user-configured context. It records repository workflow assumptions that later setup and report milestones can rely on, but the analyzer does not infer these values from GitHub and does not change scoring, rankings, collection, PR class matching, or report wording.
+
+When provided, `workflow` must include at least one supported field.
+
+Supported fields:
+
+- `primaryMergeMethod`: `merge_commit`, `squash_merge`, `rebase_merge`, `mixed`, or `unknown`.
+- `releaseStrategy`: `release_prs`, `direct_tags`, `release_branches`, `mixed`, or `unknown`.
+- `branchStrategy`: `trunk_based`, `main_plus_release_branches`, `long_lived_development_branches`, `mixed`, or `unknown`.
+
+Example:
+
+```json
+{
+  "workflow": {
+    "primaryMergeMethod": "squash_merge",
+    "releaseStrategy": "release_prs",
+    "branchStrategy": "main_plus_release_branches"
+  }
+}
+```
+
+Use stable identifiers exactly as shown above. Display labels such as "squash merges" or "release PRs" belong in CLI prompts or documentation, not in profile data.
+
+When interactive setup writes profile changes, it preserves deterministic two-space JSON formatting in place. If an existing profile uses other formatting, setup writes a generated profile copy and prints that generated path in completion output instead of rewriting the original file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "delivery-friction-analyzer",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Local GitHub pull request analytics for delivery friction reports.",
   "license": "MIT",
   "type": "module",

package/release-log.md

@@ -2,6 +2,22 @@
 
 ## Unreleased
 
+### 2026-06-18 — Workflow Profile Wizard
+
+- What changed: Interactive setup can now create repository profiles or generated profile copies with confirmed workflow context and release PR title rules.
+- Why it matters: Maintainers can capture reusable workflow assumptions during guided setup without hand-editing profile JSON or risking silent rewrites of existing profiles.
+- Who is affected: Maintainers running `--interactive` for first-time repository setup or profile updates.
+- Action needed: Review the generated or updated profile path printed in completion output before reusing it in automation.
+- PR: https://github.com/hannasdev/delivery-friction-analyzer/pull/36
+
+### 2026-06-17 — Workflow Profile Contract
+
+- What changed: Repository profiles can now declare optional workflow context for merge method, release strategy, and branch strategy using validated stable identifiers.
+- Why it matters: Future interactive setup and report milestones can rely on a documented profile contract without inferring workflow assumptions from GitHub history or changing scoring.
+- Who is affected: Maintainers authoring or validating repository profiles.
+- Action needed: Add `workflow` context only when you want to record repository workflow assumptions; existing profiles remain valid without it.
+- PR: https://github.com/hannasdev/delivery-friction-analyzer/pull/35
+
 ### 2026-06-17 — Opt-In Interactive CLI Setup
 
 - What changed: GitHub analysis now supports `--interactive` to prompt for existing run options such as repository, PR limit, profile path, output directory, dry-run mode, CSV exports, JSON completion output, and configured PR class exclusions.

package/schemas/repository-profile.schema.json

@@ -87,6 +87,22 @@
           "notes": { "type": "string" }
         }
       }
+    },
+    "workflow": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "primaryMergeMethod": {
+          "enum": ["merge_commit", "squash_merge", "rebase_merge", "mixed", "unknown"]
+        },
+        "releaseStrategy": {
+          "enum": ["release_prs", "direct_tags", "release_branches", "mixed", "unknown"]
+        },
+        "branchStrategy": {
+          "enum": ["trunk_based", "main_plus_release_branches", "long_lived_development_branches", "mixed", "unknown"]
+        }
+      },
+      "minProperties": 1
     }
   }
 }

package/src/cli/analyze-github.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { constants, realpathSync } from "node:fs";
-import { access, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { access, lstat, mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -17,6 +17,12 @@ import {
   renderRepositoryFrictionMarkdown,
 } from "../report/friction-report.js";
 import { assertValidPrClassRules } from "../profile/pr-class.js";
+import {
+  WORKFLOW_BRANCH_STRATEGIES,
+  WORKFLOW_PRIMARY_MERGE_METHODS,
+  WORKFLOW_RELEASE_STRATEGIES,
+  assertValidWorkflowContext,
+} from "../profile/workflow.js";
 
 const ALLOWED_OPTIONS = new Set([
   "repo",
@@ -182,24 +188,6 @@ function validateExcludedPrClassesAreConfigured(excludedPrClasses = [], reposito
   throw new Error(`exclude-pr-class must name configured PR class(es): ${unconfigured.join(", ")}.${available}`);
 }
 
-async function readProfile(profilePath) {
-  let profile;
-  try {
-    profile = JSON.parse(await readFile(profilePath, "utf8"));
-  } catch (error) {
-    if (error instanceof SyntaxError) {
-      throw new Error(`profile must be valid JSON: ${error.message}`);
-    }
-    throw new Error(`profile could not be read: ${error.message}`);
-  }
-  try {
-    assertValidPrClassRules(profile);
-  } catch (error) {
-    throw new Error(`profile is invalid: ${error.message}`);
-  }
-  return profile;
-}
-
 function configuredPrClassList(repositoryProfile) {
   return [...configuredPrClasses(repositoryProfile)].sort();
 }
@@ -221,6 +209,9 @@ function formatInteractivePrompt(prompt) {
   if (prompt.type === "multi-select" && prompt.choices?.length) {
     return `${prompt.message} (${prompt.choices.join(",")})${suffix}: `;
   }
+  if (prompt.type === "select" && prompt.choices?.length) {
+    return `${prompt.message} (${prompt.choices.join(",")})${suffix}: `;
+  }
   return `${prompt.message}${suffix}: `;
 }
 
@@ -284,22 +275,418 @@ function normalizeConfirmAnswer(raw, prompt) {
   throw new Error("Answer yes or no.");
 }
 
+function normalizeChoiceAnswer(raw, prompt) {
+  const value = normalizeTextAnswer(raw, prompt);
+  if (prompt.choices?.includes(value)) return value;
+  throw new Error(`${prompt.id} must be one of: ${prompt.choices.join(", ")}`);
+}
+
 function normalizeMultiSelectAnswer(raw, prompt) {
   const value = String(raw ?? "").trim();
   if (!value) return prompt.defaultValue ?? [];
   return normalizeExcludedPrClasses([value]);
 }
 
+function validateProfile(profile) {
+  assertValidPrClassRules(profile);
+  assertValidWorkflowContext(profile);
+}
+
+function parseProfileJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    if (error instanceof SyntaxError) {
+      throw new Error(`profile must be valid JSON: ${error.message}`);
+    }
+    throw error;
+  }
+}
+
+function hasTrailingPathSeparator(profilePath) {
+  return /[/\\]$/.test(profilePath);
+}
+
+async function inspectProfilePath(profilePath) {
+  if (hasTrailingPathSeparator(profilePath)) {
+    throw new Error("profile path must be a JSON file path, not a directory or special file.");
+  }
+  let profileLinkStat;
+  try {
+    profileLinkStat = await lstat(profilePath);
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return { exists: false, profile: null, text: null, isSymbolicLink: false };
+    }
+    throw error;
+  }
+  const isSymbolicLink = profileLinkStat.isSymbolicLink();
+  const profileStat = isSymbolicLink ? await stat(profilePath) : profileLinkStat;
+  if (!profileStat.isFile()) {
+    throw new Error("profile path must be a JSON file path, not a directory or special file.");
+  }
+  const text = await readFile(profilePath, "utf8");
+  const profile = parseProfileJson(text);
+  validateProfile(profile);
+  return { exists: true, profile, text, isSymbolicLink };
+}
+
+async function readProfile(profilePath) {
+  let inspected;
+  try {
+    inspected = await inspectProfilePath(profilePath);
+  } catch (error) {
+    if (error.message?.startsWith("profile must be valid JSON")) {
+      throw error;
+    }
+    if (error.message?.startsWith("invalid ")) {
+      throw new Error(`profile is invalid: ${error.message}`);
+    }
+    throw new Error(`profile could not be read: ${error.message}`);
+  }
+  if (!inspected.exists) {
+    throw new Error("profile could not be read: no such file or directory");
+  }
+  return inspected.profile;
+}
+
+function cloneJson(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function repositoryProfileFromSlug(repository) {
+  const match = REPOSITORY_SLUG.exec(repository);
+  if (!match) {
+    throw new Error("repo must use owner/name with GitHub-safe owner and name segments.");
+  }
+  return {
+    schemaVersion: "repository-profile.v1",
+    repository: {
+      owner: match[1],
+      name: match[2],
+    },
+    rules: [],
+  };
+}
+
+function formatProfile(profile) {
+  return `${JSON.stringify(profile, null, 2)}\n`;
+}
+
+function generatedProfilePath(profilePath, index = 1) {
+  const suffix = index === 1 ? ".generated.json" : `.generated-${index}.json`;
+  return /\.json$/i.test(profilePath)
+    ? profilePath.replace(/\.json$/i, suffix)
+    : `${profilePath}${suffix}`;
+}
+
+async function writeProfileFile(profilePath, profile) {
+  await mkdir(dirname(profilePath), { recursive: true });
+  await writeFile(profilePath, formatProfile(profile), { encoding: "utf8", flag: "wx" });
+}
+
+function shouldWriteGeneratedProfileAfterCreateFailure(error) {
+  return ["EEXIST", "EISDIR", "ELOOP"].includes(error.code);
+}
+
+function shouldRetryProfileReplaceAfterRenameFailure(error) {
+  return ["EEXIST", "EPERM"].includes(error.code);
+}
+
+async function replaceProfileFile(profilePath, profile, originalText) {
+  const tempPath = `${profilePath}.${process.pid}.${Date.now()}.tmp`;
+  let shouldCleanupTemp = true;
+  try {
+    await writeFile(tempPath, formatProfile(profile), { encoding: "utf8", flag: "wx" });
+    try {
+      await rename(tempPath, profilePath);
+      shouldCleanupTemp = false;
+      return true;
+    } catch (error) {
+      if (!shouldRetryProfileReplaceAfterRenameFailure(error)) {
+        throw error;
+      }
+      if (!await profileStillMatchesOriginal(profilePath, originalText)) {
+        return false;
+      }
+      await rm(profilePath, { force: true });
+      await rename(tempPath, profilePath);
+      shouldCleanupTemp = false;
+      return true;
+    }
+  } finally {
+    if (shouldCleanupTemp) {
+      await rm(tempPath, { force: true });
+    }
+  }
+}
+
+async function profileStillMatchesOriginal(profilePath, originalText) {
+  try {
+    const profileLinkStat = await lstat(profilePath);
+    if (profileLinkStat.isSymbolicLink() || !profileLinkStat.isFile()) return false;
+    return await readFile(profilePath, "utf8") === originalText;
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function writeGeneratedProfileFile(profilePath, profile) {
+  for (let index = 1; ; index += 1) {
+    const writePath = generatedProfilePath(profilePath, index);
+    try {
+      await mkdir(dirname(writePath), { recursive: true });
+      await writeFile(writePath, formatProfile(profile), { encoding: "utf8", flag: "wx" });
+      return writePath;
+    } catch (error) {
+      if (error.code === "EEXIST") continue;
+      throw error;
+    }
+  }
+}
+
+async function writeInteractiveProfile(profilePath, profile, {
+  exists,
+  originalProfile,
+  originalText,
+  originalIsSymbolicLink,
+}) {
+  const canRewriteExisting = exists
+    && !originalIsSymbolicLink
+    && originalText === formatProfile(originalProfile);
+  if (exists && !canRewriteExisting) {
+    return writeGeneratedProfileFile(profilePath, profile);
+  }
+  if (!exists) {
+    try {
+      await writeProfileFile(profilePath, profile);
+      return profilePath;
+    } catch (error) {
+      if (shouldWriteGeneratedProfileAfterCreateFailure(error)) {
+        return writeGeneratedProfileFile(profilePath, profile);
+      }
+      throw error;
+    }
+  }
+  if (!await profileStillMatchesOriginal(profilePath, originalText)) {
+    return writeGeneratedProfileFile(profilePath, profile);
+  }
+  if (!await replaceProfileFile(profilePath, profile, originalText)) {
+    return writeGeneratedProfileFile(profilePath, profile);
+  }
+  return profilePath;
+}
+
+function releaseClassRuleIndexes(profile) {
+  if (!Array.isArray(profile.prClasses)) return [];
+  return profile.prClasses
+    .map((rule, index) => rule.class === "release" ? index : -1)
+    .filter(index => index >= 0);
+}
+
+function updateableReleaseClassRuleIndex(profile) {
+  const releaseIndexes = releaseClassRuleIndexes(profile);
+  if (releaseIndexes.length !== 1) return -1;
+  const rule = profile.prClasses[releaseIndexes[0]];
+  const match = rule.match ?? {};
+  const hasTitleIncludes = typeof match.titleIncludes === "string" && match.titleIncludes.length > 0;
+  const hasTitleRegex = typeof match.titleRegex === "string" && match.titleRegex.length > 0;
+  return hasTitleIncludes && !hasTitleRegex ? releaseIndexes[0] : -1;
+}
+
+function defaultReleaseTitleIncludes(profile) {
+  const index = updateableReleaseClassRuleIndex(profile);
+  const existingIncludes = index >= 0 ? profile.prClasses[index]?.match?.titleIncludes : null;
+  return typeof existingIncludes === "string" && existingIncludes.length ? existingIncludes : "Release";
+}
+
+function nextPrClassRuleId(profile, baseId) {
+  const existingIds = new Set((profile.prClasses ?? []).map(rule => rule.id));
+  if (!existingIds.has(baseId)) return baseId;
+  for (let index = 2; ; index += 1) {
+    const candidate = `${baseId}-${index}`;
+    if (!existingIds.has(candidate)) return candidate;
+  }
+}
+
+function releasePrClassRule(profile, titleIncludes, existingRule = null) {
+  return {
+    id: existingRule?.id ?? nextPrClassRuleId(profile, "release-title"),
+    class: "release",
+    match: { ...(existingRule?.match ?? {}), titleIncludes },
+    notes: existingRule?.notes ?? "Generated by interactive setup from the configured release PR title convention.",
+  };
+}
+
+async function promptWorkflowField(promptAdapter, output, { id, message, choices, defaultValue }) {
+  return askUntilValid(promptAdapter, {
+    id,
+    type: "select",
+    message,
+    choices,
+    defaultValue,
+  }, {
+    output,
+    normalize: normalizeChoiceAnswer,
+    validate() {},
+  });
+}
+
+async function promptWorkflowProfileUpdate(promptAdapter, output, profile, { isNewProfile }) {
+  const updated = cloneJson(profile);
+  updated.workflow = {
+    primaryMergeMethod: await promptWorkflowField(promptAdapter, output, {
+      id: "primaryMergeMethod",
+      message: "Primary merge method",
+      choices: WORKFLOW_PRIMARY_MERGE_METHODS,
+      defaultValue: updated.workflow?.primaryMergeMethod ?? "unknown",
+    }),
+    releaseStrategy: await promptWorkflowField(promptAdapter, output, {
+      id: "releaseStrategy",
+      message: "Release strategy",
+      choices: WORKFLOW_RELEASE_STRATEGIES,
+      defaultValue: updated.workflow?.releaseStrategy ?? "unknown",
+    }),
+    branchStrategy: await promptWorkflowField(promptAdapter, output, {
+      id: "branchStrategy",
+      message: "Branch strategy",
+      choices: WORKFLOW_BRANCH_STRATEGIES,
+      defaultValue: updated.workflow?.branchStrategy ?? "unknown",
+    }),
+  };
+
+  if (updated.workflow.releaseStrategy === "release_prs") {
+    const suggestedReleaseTitle = defaultReleaseTitleIncludes(updated);
+    const titleIncludes = await askUntilValid(promptAdapter, {
+      id: "releasePrTitleIncludes",
+      type: "text",
+      message: `Release PR title includes (blank to skip PR class rule; suggested: ${suggestedReleaseTitle})`,
+    }, {
+      output,
+      normalize: normalizeTextAnswer,
+      validate() {},
+    });
+
+    if (titleIncludes) {
+      updated.prClasses = Array.isArray(updated.prClasses) ? [...updated.prClasses] : [];
+      const updateableReleaseIndex = updateableReleaseClassRuleIndex(updated);
+      if (updateableReleaseIndex >= 0) {
+        const shouldUpdateReleaseRule = await askUntilValid(promptAdapter, {
+          id: "updateReleasePrClass",
+          type: "confirm",
+          message: "Update existing title-based release PR class rule",
+          defaultValue: false,
+        }, {
+          output,
+          normalize: normalizeConfirmAnswer,
+          validate() {},
+        });
+        if (shouldUpdateReleaseRule) {
+          updated.prClasses[updateableReleaseIndex] = releasePrClassRule(
+            updated,
+            titleIncludes,
+            updated.prClasses[updateableReleaseIndex],
+          );
+        }
+      } else {
+        const shouldAddReleaseRule = isNewProfile
+          ? true
+          : await askUntilValid(promptAdapter, {
+            id: "addReleasePrClass",
+            type: "confirm",
+            message: "Add release PR class rule from title convention",
+            defaultValue: true,
+          }, {
+            output,
+            normalize: normalizeConfirmAnswer,
+            validate() {},
+          });
+        if (shouldAddReleaseRule) {
+          updated.prClasses.push(releasePrClassRule(updated, titleIncludes));
+        }
+      }
+    }
+  }
+
+  validateProfile(updated);
+  return updated;
+}
+
+async function maybeConfigureInteractiveProfile(promptAdapter, output, profileState, repository) {
+  const isNewProfile = !profileState.exists;
+  const originalProfile = profileState.profile;
+  let profile = isNewProfile ? repositoryProfileFromSlug(repository) : cloneJson(originalProfile);
+
+  if (isNewProfile) {
+    const shouldCreateProfile = await askUntilValid(promptAdapter, {
+      id: "createProfile",
+      type: "confirm",
+      message: "Create repository profile at this path",
+      defaultValue: true,
+    }, {
+      output,
+      normalize: normalizeConfirmAnswer,
+      validate() {},
+    });
+    if (!shouldCreateProfile) {
+      throw new Error("Repository profile is required.");
+    }
+  } else {
+    const shouldConfigureWorkflow = await askUntilValid(promptAdapter, {
+      id: "configureWorkflow",
+      type: "confirm",
+      message: "Configure repository workflow profile fields",
+      defaultValue: false,
+    }, {
+      output,
+      normalize: normalizeConfirmAnswer,
+      validate() {},
+    });
+    if (!shouldConfigureWorkflow) {
+      return {
+        profile,
+        profilePath: profileState.profilePath,
+        savedProfilePath: null,
+      };
+    }
+  }
+
+  profile = await promptWorkflowProfileUpdate(promptAdapter, output, profile, { isNewProfile });
+  const savedProfilePath = await writeInteractiveProfile(profileState.profilePath, profile, {
+    exists: profileState.exists,
+    originalProfile,
+    originalText: profileState.text,
+    originalIsSymbolicLink: profileState.isSymbolicLink,
+  });
+  return {
+    profile,
+    profilePath: savedProfilePath,
+    savedProfilePath,
+  };
+}
+
 async function promptProfilePath(promptAdapter, output, prompt) {
-  let profile = null;
+  let profileState = null;
   const profilePath = await askUntilValid(promptAdapter, prompt, {
     output,
     normalize: normalizeTextAnswer,
     async validate(value) {
-      profile = await readProfile(value);
+      if (!value) throw new Error("Repository profile path is required.");
+      try {
+        profileState = await inspectProfilePath(value);
+      } catch (error) {
+        if (error.message?.startsWith("profile must be valid JSON")) {
+          throw error;
+        }
+        if (error.message?.startsWith("invalid ")) {
+          throw new Error(`profile is invalid: ${error.message}`);
+        }
+        throw new Error(`profile could not be read: ${error.message}`);
+      }
     },
   });
-  return { profilePath, profile };
+  return { profilePath, ...profileState };
 }
 
 function hasOwnOption(options, key) {
@@ -319,6 +706,7 @@ export async function collectInteractiveAnalyzeGithubOptions(options, {
   input = process.stdin,
   output = process.stderr,
   isInteractiveTerminal = Boolean(input?.isTTY),
+  onSavedProfilePath = null,
 } = {}) {
   if (!isInteractiveTerminal) {
     throw new Error("interactive mode requires a terminal. Re-run with --repo <owner/name> --limit <1-100> --profile <path> --out <directory>, or provide a TTY for prompts.");
@@ -329,6 +717,7 @@ export async function collectInteractiveAnalyzeGithubOptions(options, {
   const resolved = { ...options };
   delete resolved.interactivePromptDefaults;
   let repositoryProfile = null;
+  let profileState = null;
 
   try {
     if (!resolved.repository) {
@@ -362,11 +751,34 @@ export async function collectInteractiveAnalyzeGithubOptions(options, {
         type: "path",
         message: "Repository profile path",
       });
-      resolved.profilePath = prompted.profilePath;
-      repositoryProfile = prompted.profile;
+      profileState = prompted;
     } else {
-      repositoryProfile = await readProfile(resolved.profilePath);
+      try {
+        profileState = {
+          profilePath: resolved.profilePath,
+          ...await inspectProfilePath(resolved.profilePath),
+        };
+      } catch (error) {
+        if (error.message?.startsWith("profile must be valid JSON")) {
+          throw error;
+        }
+        if (error.message?.startsWith("invalid ")) {
+          throw new Error(`profile is invalid: ${error.message}`);
+        }
+        throw new Error(`profile could not be read: ${error.message}`);
+      }
+    }
+    resolved.profilePath = profileState.profilePath;
+
+    const profileUpdate = await maybeConfigureInteractiveProfile(adapter, output, profileState, resolved.repository);
+    resolved.profilePath = profileUpdate.profilePath;
+    if (profileUpdate.savedProfilePath) {
+      resolved.savedProfilePath = profileUpdate.savedProfilePath;
+      if (typeof onSavedProfilePath === "function") {
+        onSavedProfilePath(profileUpdate.savedProfilePath);
+      }
     }
+    repositoryProfile = profileUpdate.profile;
 
     if (!resolved.outDir) {
       resolved.outDir = await askUntilValid(adapter, {
@@ -610,8 +1022,8 @@ function attachCollectionCoverage(report, sourceBundle) {
   };
 }
 
-function summarizeResult({ dryRun, outDir, paths, sourceBundle, metrics, report, requestedLimit, sampledLimit, csv, analysisFilter }) {
-  return {
+function summarizeResult({ dryRun, outDir, paths, sourceBundle, metrics, report, requestedLimit, sampledLimit, csv, analysisFilter, savedProfilePath }) {
+  const summary = {
     ok: true,
     dryRun,
     csvArtifactsEnabled: Boolean(csv),
@@ -626,6 +1038,10 @@ function summarizeResult({ dryRun, outDir, paths, sourceBundle, metrics, report,
     totals: metrics?.totals ?? null,
     topBottleneckIds: report?.summary?.topBottleneckIds ?? null,
   };
+  if (savedProfilePath) {
+    summary.savedProfilePath = savedProfilePath;
+  }
+  return summary;
 }
 
 function applyPrClassFilter(normalized, excludedPrClasses = []) {
@@ -697,6 +1113,7 @@ export async function runAnalyzeGithub(options, {
       sampledLimit: collectionLimit,
       csv: false,
       analysisFilter: null,
+      savedProfilePath: options.savedProfilePath,
     });
   }
 
@@ -745,6 +1162,7 @@ export async function runAnalyzeGithub(options, {
     sampledLimit: collectionLimit,
     csv: csvEnabled,
     analysisFilter: normalized.analysisFilter ?? null,
+    savedProfilePath: options.savedProfilePath,
   });
 }
 
@@ -814,6 +1232,10 @@ export function formatAnalyzeGithubCompletion(result) {
     );
   }
 
+  if (result.savedProfilePath) {
+    lines.push(`Repository profile saved: ${result.savedProfilePath}.`);
+  }
+
   lines.push(`Collection coverage: ${result.collectionCoverage?.status ?? "unknown"}.`);
 
   const caveats = coverageCaveats(result.collectionCoverage);
@@ -845,36 +1267,50 @@ export async function runAnalyzeGithubCli(argv, {
   promptAdapter = null,
   isInteractiveTerminal = Boolean(stdin?.isTTY),
 } = {}) {
-  const options = parseAnalyzeGithubArgs(argv);
-  if (options.help) {
-    stdout.write(USAGE);
-    return null;
-  }
-
-  const resolvedOptions = options.interactive
-    ? await collectInteractiveAnalyzeGithubOptions({
-      ...options,
-      interactivePromptDefaults: {
-        dryRun: !options.dryRun,
-        csv: options.csv !== false,
-        json: !options.json,
-      },
-    }, {
-      promptAdapter,
-      input: stdin,
-      output: stderr,
-      isInteractiveTerminal,
-    })
-    : options;
-  const runOptions = {
-    onProgress: message => writeProgress(message, stderr),
-  };
-  if (provider !== undefined) runOptions.provider = provider;
-  if (now !== undefined) runOptions.now = now;
+  let savedProfilePath = null;
+  try {
+    const options = parseAnalyzeGithubArgs(argv);
+    if (options.help) {
+      stdout.write(USAGE);
+      return null;
+    }
 
-  const result = await runAnalyzeGithub(resolvedOptions, runOptions);
-  writeAnalyzeGithubCompletion(result, { json: resolvedOptions.json, stdout });
-  return result;
+    const resolvedOptions = options.interactive
+      ? await collectInteractiveAnalyzeGithubOptions({
+        ...options,
+        interactivePromptDefaults: {
+          dryRun: !options.dryRun,
+          csv: options.csv !== false,
+          json: !options.json,
+        },
+      }, {
+        promptAdapter,
+        input: stdin,
+        output: stderr,
+        isInteractiveTerminal,
+        onSavedProfilePath(path) {
+          savedProfilePath = path;
+        },
+      })
+      : options;
+    if (resolvedOptions.savedProfilePath) {
+      savedProfilePath = resolvedOptions.savedProfilePath;
+    }
+    const runOptions = {
+      onProgress: message => writeProgress(message, stderr),
+    };
+    if (provider !== undefined) runOptions.provider = provider;
+    if (now !== undefined) runOptions.now = now;
+
+    const result = await runAnalyzeGithub(resolvedOptions, runOptions);
+    writeAnalyzeGithubCompletion(result, { json: resolvedOptions.json, stdout });
+    return result;
+  } catch (error) {
+    if (savedProfilePath) {
+      stderr.write(`Repository profile saved before failure: ${savedProfilePath}.\n`);
+    }
+    throw error;
+  }
 }
 
 async function main(argv) {

package/src/normalize/github-fixture.js

@@ -1,6 +1,7 @@
 import { classifyCommentSource, groupByCommentSource } from "../github/comment-source.js";
 import { classifyFilePath } from "../profile/file-role.js";
 import { assertValidPrClassRules, classifyPullRequest } from "../profile/pr-class.js";
+import { assertValidWorkflowContext } from "../profile/workflow.js";
 
 function minDate(values) {
   return values.filter(Boolean).sort()[0] ?? null;
@@ -112,6 +113,7 @@ function normalizeCommit(commit) {
 export function normalizeFixtureBundle(bundle, { repositoryProfile } = {}) {
   const profile = repositoryProfile ?? {};
   assertValidPrClassRules(profile);
+  assertValidWorkflowContext(profile);
 
   const pullRequests = (bundle.pullRequests ?? []).map(pr => {
     const reviewDates = (pr.reviews ?? []).map(review => review.submittedAt);

package/src/profile/workflow.js

@@ -0,0 +1,75 @@
+export const WORKFLOW_PRIMARY_MERGE_METHODS = Object.freeze([
+  "merge_commit",
+  "squash_merge",
+  "rebase_merge",
+  "mixed",
+  "unknown",
+]);
+
+export const WORKFLOW_RELEASE_STRATEGIES = Object.freeze([
+  "release_prs",
+  "direct_tags",
+  "release_branches",
+  "mixed",
+  "unknown",
+]);
+
+export const WORKFLOW_BRANCH_STRATEGIES = Object.freeze([
+  "trunk_based",
+  "main_plus_release_branches",
+  "long_lived_development_branches",
+  "mixed",
+  "unknown",
+]);
+
+const WORKFLOW_FIELDS = Object.freeze({
+  primaryMergeMethod: WORKFLOW_PRIMARY_MERGE_METHODS,
+  releaseStrategy: WORKFLOW_RELEASE_STRATEGIES,
+  branchStrategy: WORKFLOW_BRANCH_STRATEGIES,
+});
+
+function allowedValues(values) {
+  return values.join(", ");
+}
+
+export function validateWorkflowContext(profile = {}) {
+  const errors = [];
+  if (!profile || typeof profile !== "object" || Array.isArray(profile)) {
+    return errors;
+  }
+
+  if (!Object.prototype.hasOwnProperty.call(profile, "workflow")) {
+    return errors;
+  }
+
+  const workflow = profile.workflow;
+  if (!workflow || typeof workflow !== "object" || Array.isArray(workflow)) {
+    return ["workflow must be an object when provided"];
+  }
+  if (Object.keys(workflow).length === 0) {
+    return ["workflow must include at least one field when provided"];
+  }
+
+  for (const key of Object.keys(workflow)) {
+    if (!Object.prototype.hasOwnProperty.call(WORKFLOW_FIELDS, key)) {
+      errors.push(`workflow.${key} is not supported`);
+    }
+  }
+
+  for (const [field, values] of Object.entries(WORKFLOW_FIELDS)) {
+    const value = workflow[field];
+    if (value === undefined) continue;
+    if (!values.includes(value)) {
+      errors.push(`workflow.${field} must be one of: ${allowedValues(values)}`);
+    }
+  }
+
+  return errors;
+}
+
+export function assertValidWorkflowContext(profile = {}) {
+  const errors = validateWorkflowContext(profile);
+  if (errors.length > 0) {
+    throw new Error(`invalid workflow profile context: ${errors.join("; ")}`);
+  }
+}