delivery-friction-analyzer 0.4.0 → 0.6.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/contracts/friction-report.md

@@ -27,6 +27,7 @@ The command reads local `friction-metrics.v1` JSON and writes deterministic `fri
 - `metricVersion`: source metrics contract version.
 - `targetRepository`: analyzed repository identity; live analysis sample size is encoded as `targetRepository.analysisPullRequestLimit` from collection metadata.
 - `analysisFilter`: optional metadata for explicit filters applied before metrics computation, including excluded PR classes and before/after PR counts.
+- `configuredWorkflow`: optional user-configured workflow context from the repository profile. It is not observed GitHub evidence and does not change scoring, ranking, CSV exports, or PR class matching.
 - `summary`: repository totals and top bottleneck identifiers.
 - `coverage`: PR-open diff, workflow-run, and review-thread coverage counts plus caveats.
 - `commentSources`: total and source-grouped review comments for Copilot, human, bot, scanner, author replies, and unknown sources.
@@ -55,6 +56,7 @@ The Markdown renderer presents the same report data for human review:
 - a top-of-report focus snapshot that names focus areas, action categories, evidence reviewed, and confidence caveats before detailed bottlenecks;
 - a compact recommendation-category snapshot before detailed bottlenecks, with the full category reference retained later in the report;
 - a short "How To Read This Report" guide that distinguishes observed evidence, interpretation, recommendations, and caveats;
+- a configured workflow context section only when repository profile workflow fields are present, labeled as user-configured profile context rather than observed GitHub evidence;
 - evidence-quality and coverage tables before detailed recommendations;
 - key findings that highlight top bottlenecks, strongest displayed signal, outlier caveats, PR class caveats, and coverage caveats;
 - a PR class context table that shows analyzed PR counts, changed lines, sample share, and classification sources by class;
@@ -104,6 +106,7 @@ Full live analysis writes `methodology.md` as a hybrid artifact: stable explanat
 
 - target repository and report/metric versions;
 - profile path when available;
+- configured workflow context when supplied by the repository profile, labeled as user-configured context rather than observed GitHub evidence;
 - requested and collected PR counts;
 - collection coverage status and API-family diagnostics;
 - scoring, ranking, dominance, sensitivity, and limitation explanations;

package/docs/reference/repository-profile.md

@@ -54,9 +54,11 @@ 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 M2 does not infer these values from GitHub and does not change scoring, rankings, collection, PR class matching, or report wording.
+`workflow` is optional user-configured context. It records repository workflow assumptions that reports can surface as configured profile context, but the analyzer does not infer these values from GitHub and does not change scoring, rankings, collection, CSV exports, or PR class matching.
 
 When provided, `workflow` must include at least one supported field.
 
@@ -79,3 +81,5 @@ Example:
 ```
 
 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.4.0",
+  "version": "0.6.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-19 — Workflow Context Surfacing
+
+- What changed: Friction reports and methodology now show configured repository workflow context from the profile when it is present.
+- Why it matters: Maintainers can see merge, release, and branch assumptions beside report evidence without mistaking them for observed GitHub data or scoring inputs.
+- Who is affected: Maintainers and contributors reviewing generated reports or authoring repository profiles with `workflow` context.
+- Action needed: None.
+- PR: https://github.com/hannasdev/delivery-friction-analyzer/pull/37
+
+### 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.

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,7 +17,12 @@ import {
   renderRepositoryFrictionMarkdown,
 } from "../report/friction-report.js";
 import { assertValidPrClassRules } from "../profile/pr-class.js";
-import { assertValidWorkflowContext } from "../profile/workflow.js";
+import {
+  WORKFLOW_BRANCH_STRATEGIES,
+  WORKFLOW_PRIMARY_MERGE_METHODS,
+  WORKFLOW_RELEASE_STRATEGIES,
+  assertValidWorkflowContext,
+} from "../profile/workflow.js";
 
 const ALLOWED_OPTIONS = new Set([
   "repo",
@@ -183,25 +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);
-    assertValidWorkflowContext(profile);
-  } catch (error) {
-    throw new Error(`profile is invalid: ${error.message}`);
-  }
-  return profile;
-}
-
 function configuredPrClassList(repositoryProfile) {
   return [...configuredPrClasses(repositoryProfile)].sort();
 }
@@ -223,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}: `;
 }
 
@@ -286,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) {
@@ -321,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.");
@@ -331,6 +717,7 @@ export async function collectInteractiveAnalyzeGithubOptions(options, {
   const resolved = { ...options };
   delete resolved.interactivePromptDefaults;
   let repositoryProfile = null;
+  let profileState = null;
 
   try {
     if (!resolved.repository) {
@@ -364,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, {
@@ -612,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),
@@ -628,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 = []) {
@@ -699,6 +1113,7 @@ export async function runAnalyzeGithub(options, {
       sampledLimit: collectionLimit,
       csv: false,
       analysisFilter: null,
+      savedProfilePath: options.savedProfilePath,
     });
   }
 
@@ -708,7 +1123,10 @@ export async function runAnalyzeGithub(options, {
     options.excludedPrClasses ?? [],
   );
   const metrics = computeRepositoryMetrics(normalized);
-  const report = attachCollectionCoverage(generateRepositoryFrictionReport(metrics), sourceBundle);
+  const report = attachCollectionCoverage(
+    generateRepositoryFrictionReport(metrics, { workflowContext: repositoryProfile.workflow }),
+    sourceBundle,
+  );
   const markdown = `${renderRepositoryFrictionMarkdown(report)}${collectionCoverageMarkdown(sourceBundle)}`;
   const methodology = renderRepositoryFrictionMethodology({
     report,
@@ -747,6 +1165,7 @@ export async function runAnalyzeGithub(options, {
     sampledLimit: collectionLimit,
     csv: csvEnabled,
     analysisFilter: normalized.analysisFilter ?? null,
+    savedProfilePath: options.savedProfilePath,
   });
 }
 
@@ -816,6 +1235,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);
@@ -847,36 +1270,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/report/evidence-artifacts.js

@@ -1,3 +1,9 @@
+import {
+  CONFIGURED_WORKFLOW_NOTE,
+  configuredWorkflowEntries,
+  hasConfiguredWorkflowContext,
+} from "./friction-report.js";
+
 const BOT_OR_SCANNER_SOURCES = new Set([
   "copilot",
   "github_actions_bot",
@@ -336,6 +342,21 @@ function formatSensitivitySummaries(report) {
   }).join("\n");
 }
 
+function formatConfiguredWorkflowContext(report) {
+  const configuredWorkflow = report.configuredWorkflow;
+  if (!hasConfiguredWorkflowContext(configuredWorkflow)) return [];
+
+  return [
+    "## Configured Workflow Context",
+    "",
+    configuredWorkflow.note ?? CONFIGURED_WORKFLOW_NOTE,
+    "",
+    ...configuredWorkflowEntries(configuredWorkflow)
+      .map(entry => `- ${entry.label}: ${entry.valueLabel}`),
+    "",
+  ];
+}
+
 export function renderRepositoryFrictionMethodology({
   report,
   sourceBundle,
@@ -373,6 +394,7 @@ export function renderRepositoryFrictionMethodology({
     "",
     "The repository profile maps file paths to categories, roles, and functional surfaces. Those classifications drive non-generated changed-line counts, support-surface summaries, planning-document signals, and low-signal weighting.",
     "",
+    ...formatConfiguredWorkflowContext(report),
     "## Scores And Rankings",
     "",
     "The report ranks bottlenecks by transparent component metrics from `friction-metrics.v1`: review churn, change scope (the internal changed-file-spread signal: core files touched plus directories touched plus functional surfaces touched), validation gap, planning gap, review surprise, and fix amplification. These are not an opaque composite score, and they are not individual contributor or reviewer rankings.",

package/src/report/friction-report.js

@@ -61,6 +61,28 @@ const RANKING_SIGNAL_LABELS = new Map([
   ["fixAmplification", "fix amplification"],
 ]);
 
+const WORKFLOW_CONTEXT_FIELDS = [
+  ["primaryMergeMethod", "Primary merge method"],
+  ["releaseStrategy", "Release strategy"],
+  ["branchStrategy", "Branch strategy"],
+];
+
+const WORKFLOW_CONTEXT_VALUE_LABELS = new Map([
+  ["merge_commit", "Merge commit"],
+  ["squash_merge", "Squash merge"],
+  ["rebase_merge", "Rebase merge"],
+  ["release_prs", "Release PRs"],
+  ["direct_tags", "Direct tags"],
+  ["release_branches", "Release branches"],
+  ["trunk_based", "Trunk-based"],
+  ["main_plus_release_branches", "Main plus release branches"],
+  ["long_lived_development_branches", "Long-lived development branches"],
+  ["mixed", "Mixed"],
+  ["unknown", "Unknown"],
+]);
+
+export const CONFIGURED_WORKFLOW_NOTE = "Configured workflow context comes from the repository profile. It is user-configured context, not observed GitHub evidence, and it does not change scores, rankings, CSV exports, or PR class matching.";
+
 const BOTTLENECK_DEFINITIONS = [
   {
     id: "review-churn",
@@ -563,6 +585,42 @@ function summarizeRecommendationCategories(bottlenecks) {
   }));
 }
 
+export function normalizeConfiguredWorkflowContext(workflowContext) {
+  if (!workflowContext || typeof workflowContext !== "object" || Array.isArray(workflowContext)) {
+    return null;
+  }
+
+  const configuredWorkflow = {
+    source: "repository_profile",
+    note: CONFIGURED_WORKFLOW_NOTE,
+  };
+  for (const [field] of WORKFLOW_CONTEXT_FIELDS) {
+    if (workflowContext[field] !== undefined) {
+      configuredWorkflow[field] = workflowContext[field];
+    }
+  }
+
+  return WORKFLOW_CONTEXT_FIELDS.some(([field]) => configuredWorkflow[field] !== undefined)
+    ? configuredWorkflow
+    : null;
+}
+
+export function configuredWorkflowEntries(configuredWorkflow) {
+  if (!configuredWorkflow || typeof configuredWorkflow !== "object") return [];
+  return WORKFLOW_CONTEXT_FIELDS
+    .filter(([field]) => configuredWorkflow[field] !== undefined)
+    .map(([field, label]) => ({
+      field,
+      label,
+      value: configuredWorkflow[field],
+      valueLabel: WORKFLOW_CONTEXT_VALUE_LABELS.get(configuredWorkflow[field]) ?? configuredWorkflow[field],
+    }));
+}
+
+export function hasConfiguredWorkflowContext(configuredWorkflow) {
+  return configuredWorkflowEntries(configuredWorkflow).length > 0;
+}
+
 function evidenceSignature(bottleneck) {
   return (bottleneck.observedData ?? [])
     .map(evidence => evidence.number)
@@ -712,16 +770,19 @@ function summarizeSensitivity(metricsSummary, baselineBottlenecks) {
   };
 }
 
-export function generateRepositoryFrictionReport(metricsSummary) {
+export function generateRepositoryFrictionReport(metricsSummary, options = {}) {
+  const { workflowContext } = options ?? {};
   const prClasses = summarizePrClasses(metricsSummary);
   const bottlenecksWithSharedSignalKeys = summarizeBottlenecks(metricsSummary, prClasses);
   const sharedSignals = summarizeSharedSignals(bottlenecksWithSharedSignalKeys);
   const bottlenecks = bottlenecksWithSharedSignalKeys.map(({ rankingKey, ...bottleneck }) => bottleneck);
+  const configuredWorkflow = normalizeConfiguredWorkflowContext(workflowContext);
   return {
     reportVersion: FRICTION_REPORT_VERSION,
     metricVersion: metricsSummary.metricVersion,
     targetRepository: metricsSummary.targetRepository,
     ...(metricsSummary.analysisFilter ? { analysisFilter: metricsSummary.analysisFilter } : {}),
+    ...(configuredWorkflow ? { configuredWorkflow } : {}),
     summary: {
       pullRequests: metricsSummary.totals?.pullRequests ?? 0,
       changedLines: metricsSummary.totals?.changedLines ?? 0,
@@ -1152,6 +1213,23 @@ function renderPrClassContext(prClasses) {
   ].join("\n");
 }
 
+function renderConfiguredWorkflowContext(configuredWorkflow) {
+  const entries = configuredWorkflowEntries(configuredWorkflow);
+  if (!entries.length) return "";
+
+  return [
+    "## Configured Workflow Context",
+    "",
+    configuredWorkflow.note ?? CONFIGURED_WORKFLOW_NOTE,
+    "",
+    renderMarkdownTable(
+      ["Field", "Configured value"],
+      entries.map(entry => [entry.label, entry.valueLabel]),
+    ),
+    "",
+  ].join("\n");
+}
+
 function classDominanceCaveat(bottleneck) {
   return bottleneck.classDominance?.status === "single_class_dominates"
     ? bottleneck.classDominance.note
@@ -1299,7 +1377,13 @@ export function renderRepositoryFrictionMarkdown(report) {
     "- Interpretation is the analyzer's explanation of what the observed evidence suggests.",
     "- Recommendation is a workflow intervention to consider; the report does not modify repositories.",
     "- Confidence and caveats call out outliers, missing coverage, and evidence-quality limits before you act.",
+    ...(hasConfiguredWorkflowContext(report.configuredWorkflow)
+      ? ["- Configured workflow context, when shown, comes from the repository profile and is not observed GitHub evidence."]
+      : []),
     "",
+    ...(hasConfiguredWorkflowContext(report.configuredWorkflow)
+      ? [renderConfiguredWorkflowContext(report.configuredWorkflow)]
+      : []),
     "## Evidence Quality And Coverage",
     "",
     renderCoverageSummary(report.coverage),
@@ -1370,6 +1454,9 @@ export function renderRepositoryFrictionMarkdown(report) {
     "- Bottlenecks are ranked by their strongest representative observed signal, with stable category order only used to break ties.",
     "- Recommendations are inferred from transparent component evidence and representative PR examples; they are not automated changes.",
     "- Missing or partial GitHub data remains visible in coverage tables rather than being inferred from unrelated fields.",
+    ...(hasConfiguredWorkflowContext(report.configuredWorkflow)
+      ? ["- Configured workflow context is user-configured repository-profile context; it does not change scoring, ranking, CSV exports, or PR class matching."]
+      : []),
     "- Sensitivity analysis, when present, excludes one dominant representative PR at a time to show robustness context without changing the baseline ranking.",
     report.analysisFilter?.excludedPrClasses?.length
       ? "- PR class filtering was explicitly applied before metrics and ranking; PR class context still supports interpretation of the filtered sample."