lee-spec-kit 0.9.0 → 0.9.1

package/dist/index.js

@@ -12,6 +12,7 @@ import { spawn, execFileSync, spawnSync } from 'child_process';
 import os from 'os';
 import crypto, { createHash } from 'crypto';
 import fs21 from 'fs';
+import fs26 from 'fs/promises';
 
 async function walkFiles(fsAdapter, rootDir, options = {}) {
   const out = [];
@@ -1231,7 +1232,8 @@ var ENGINE_MANAGED_AGENT_FILES = [
   "agents.md",
   "git-workflow.md",
   "issue-template.md",
-  "pr-template.md"
+  "pr-template.md",
+  "ui-ux-design.md"
 ];
 var ENGINE_MANAGED_AGENT_DIRS = ["skills"];
 var ENGINE_MANAGED_FEATURE_PATH = path8.join(
@@ -1307,7 +1309,7 @@ Before taking the next workflow step:
 13. When \`workflow-stage --json\` returns \`nextAction.category === "pre_pr_review"\` and \`nextAction.executor === "subagent"\`, delegate a fresh read-only review using the returned \`model\`, \`reasoningEffort\`, and \`onUnavailable\` policy; do not select or require a named review skill
 14. The Pre-PR review subagent returns findings without modifying code; the main agent remediates findings and records the actual reviewer metadata, reviewed diff scope, evidence, and final decision
 15. For a local workflow, do not report completion directly after implementation approval; follow the exact returned \`local merge\` / \`local cleanup\` commands until \`workflow-stage\` proves integration, verification, and cleanup and returns \`done\`
-16. In a \`local-ff\` workflow, present the implementation approval summary exactly as returned because that checkpoint authorizes the remaining fast-forward integration, post-merge checks, and configured local cleanup; ask again at \`local_merge\` only when that category is explicitly configured as required
+16. In a \`local-ff\` or \`local-squash\` workflow, keep implementation approval and local merge approval distinct when \`local_merge\` is required: the first accepts the implementation, and the second authorizes the configured integration strategy, post-merge checks, and local cleanup
 
 Approval and remote actions:
 
@@ -1315,14 +1317,20 @@ Approval and remote actions:
 - If \`workflow-stage --json\` reports \`approvalRequired === true\`, stop at that boundary and ask the user before proceeding
 - If \`workflow-stage --json\` returns labeled \`actionOptions\` at any approval boundary, keep the same option labels and exact \`reply\` tokens in the user prompt and do not improvise different reply formats
 - If \`workflow-stage --json\` reports \`nextAction.category === "task_commit"\`, make the docs commit and project commit for the just-finished task before starting the next task or moving to the next stage
-- Before \`git commit\`, prefer \`npx lee-spec-kit commit-audit --json\` when hooks or manual checks need commit-time docs path enforcement
+- Before \`git commit\`, prefer \`npx lee-spec-kit commit-audit --json\`; Feature-scoped commits use \`#123\` when an Issue is linked and the stable Feature ID such as \`F027\` for issue-less local workflows
 - Before remote GitHub actions, share the plan or artifact being sent
 - Respect repo policy from docs and config first; hooks only enforce guardrails and continuation checks
 
 Validation:
 
-- Prefer \`npx lee-spec-kit commit-audit --json\` for commit-time staged docs path validation
+- Prefer \`npx lee-spec-kit commit-audit --json\` for commit-time staged docs path validation and canonical commit-subject validation
 - Prefer \`npx lee-spec-kit workflow-audit --json\` as the default docs-sync validator for Codex hooks and end-of-turn checks; it expects the active feature docs to carry one fresh \`lee-spec-kit:workflow-sync\` marker after meaningful code/doc sync
+
+Optional UI/UX design policy:
+
+- Only when the user request explicitly mentions a design system, UI/visual redesign, design consistency, shared UI/component-library consolidation, branding/theme/token redesign, or implementation from Figma/design images, read and apply \`npx lee-spec-kit docs get ui-ux-design --json\`
+- Do not apply that policy merely because the target is web/frontend, to a non-UI/backend Feature, or to a simple bug fix unrelated to durable design rules
+- Treat it as optional guidance, not a \`requiredDocs\` entry or workflow approval gate
 `;
 function renderManagedSegment(lang, docsRepo) {
   return `${LEE_SPEC_KIT_AGENTS_BEGIN}
@@ -1887,7 +1895,8 @@ async function getConfig(cwd) {
 // src/config/types.ts
 var DEFAULT_APPROVAL_REQUIRE_CHECK_CATEGORIES = [
   "spec_approve",
-  "implementation_approve"
+  "implementation_approve",
+  "local_merge"
 ];
 var PRE_PR_REVIEW_REASONING_EFFORTS = [
   "low",
@@ -3481,6 +3490,11 @@ function isLegacyGeneratedApprovalConfig(approval) {
   ];
   return !overrideKeys.some((key) => hasOwnKey2(approval, key));
 }
+function isPreviousDefaultApprovalConfig(approval) {
+  const keys = Object.keys(approval).sort();
+  const categories = Array.isArray(approval.requireCheckCategories) ? approval.requireCheckCategories : [];
+  return JSON.stringify(keys) === JSON.stringify(["default", "mode", "requireCheckCategories"]) && approval.mode === "category" && approval.default === "skip" && categories.length === 2 && categories[0] === "spec_approve" && categories[1] === "implementation_approve";
+}
 function updateCommand(program2) {
   program2.command("update").description("Update docs templates to the latest version").option("--agents", "Update agents/ folder only").option("--agents-md", "Sync project-scoped AGENTS.md entrypoint").option(
     "-f, --force",
@@ -3720,7 +3734,7 @@ async function backfillMissingConfigDefaults(cwd, docsDir) {
       "none",
       "workflow.completionStrategy"
     );
-    if (workflow.completionStrategy !== "local-ff" && workflow.completionStrategy !== "none") {
+    if (workflow.completionStrategy !== "local-ff" && workflow.completionStrategy !== "local-squash" && workflow.completionStrategy !== "none") {
       workflow.completionStrategy = "none";
       changedPaths.push("workflow.completionStrategy");
     }
@@ -3822,7 +3836,7 @@ async function backfillMissingConfigDefaults(cwd, docsDir) {
     const migration = migrateLegacyApprovalSettings(approval);
     raw.approval = migration.approval;
     changedPaths.push(...migration.changedPaths);
-    if (isPlainObject(raw.approval) && isLegacyGeneratedApprovalConfig(raw.approval)) {
+    if (isPlainObject(raw.approval) && (isLegacyGeneratedApprovalConfig(raw.approval) || isPreviousDefaultApprovalConfig(raw.approval))) {
       raw.approval = createDefaultApprovalConfig();
       changedPaths.push("approval");
     }
@@ -6697,6 +6711,14 @@ var BUILTIN_DOC_DEFINITIONS = [
     id: "split-feature",
     title: { ko: "feature \uBD84\uD560 \uAC00\uC774\uB4DC", en: "feature split guide" },
     relativePath: (_, lang) => path8.join(lang, "common", "agents", "skills", "split-feature.md")
+  },
+  {
+    id: "ui-ux-design",
+    title: {
+      ko: "\uC120\uD0DD\uC801 UI/UX \uB514\uC790\uC778 \uBB38\uC11C \uC815\uCC45",
+      en: "Optional UI/UX Design Documentation Policy"
+    },
+    relativePath: (_, lang) => path8.join(lang, "common", "agents", "ui-ux-design.md")
   }
 ];
 var DOC_FOLLOWUPS = {
@@ -6717,7 +6739,8 @@ var DOC_FOLLOWUPS = {
   "execute-task": ["git-workflow", "split-feature"],
   "create-issue": ["issue-doc"],
   "create-pr": ["pr-doc"],
-  "split-feature": []
+  "split-feature": [],
+  "ui-ux-design": []
 };
 function getBuiltinDocIds() {
   return BUILTIN_DOC_DEFINITIONS.map((doc) => doc.id);
@@ -6736,6 +6759,7 @@ function normalizeBuiltinDocId(input) {
   if (normalized === "split-feature") {
     return "split-feature";
   }
+  if (normalized === "ui-ux-design") return "ui-ux-design";
   if (normalized === "agents") return "agents";
   return null;
 }
@@ -7197,11 +7221,9 @@ function findPlaceholderDecisionRange(content) {
   const block = content.slice(match.index, end);
   const isPlaceholder = /\{(?:Decision Title|결정 제목)\}/.test(match[0]) || /-\s+\*\*Decision\*\*:\s*(Final choice|최종 선택)/.test(block);
   if (!isPlaceholder) return null;
-  const sequence = Number(match[1] || "1");
   return {
     start: match.index,
-    end,
-    sequence: Number.isFinite(sequence) ? sequence : 1
+    end
   };
 }
 function formatOptions(options) {
@@ -7242,7 +7264,7 @@ async function runDecisionAdd(featureName, options) {
   const optionItems = (options.option || []).map((value) => value.trim()).filter(Boolean);
   const content = await fs.readFile(target.path, "utf-8");
   const placeholderRange = findPlaceholderDecisionRange(content);
-  const decisionSequence = placeholderRange?.sequence ?? getNextDecisionSequence(content);
+  const decisionSequence = placeholderRange ? 1 : getNextDecisionSequence(content);
   const decisionId = `D${String(decisionSequence).padStart(3, "0")}`;
   const recordedAt = localDate();
   const block = formatDecisionBlock({
@@ -7551,6 +7573,44 @@ function integrationsCommand(program2) {
   registerCodexIntegration(integrations);
   registerCodexHooksIntegration(integrations);
 }
+
+// src/utils/commit-conventions.ts
+var PROJECT_COMMIT_TYPES = [
+  "feat",
+  "fix",
+  "refactor",
+  "test",
+  "style",
+  "chore"
+];
+function resolveFeatureCommitScope(input) {
+  const issueNumber = Number(input.issueNumber || 0);
+  if (Number.isInteger(issueNumber) && issueNumber > 0) {
+    return `#${issueNumber}`;
+  }
+  if (input.workflowMode !== "local") {
+    return null;
+  }
+  const featureId = String(input.featureId || "").trim().toUpperCase();
+  return /^F\d{3,}$/.test(featureId) ? featureId : null;
+}
+function matchesProjectCommitConvention(message, scope) {
+  return matchesCommitConvention(message, scope, PROJECT_COMMIT_TYPES);
+}
+function matchesDocsCommitConvention(message, scope) {
+  return matchesCommitConvention(message, scope, ["docs"]);
+}
+function matchesCommitConvention(message, scope, types) {
+  const normalized = String(message || "").trim();
+  const normalizedScope = String(scope || "").trim();
+  if (!normalized || !normalizedScope) return false;
+  const typePattern = types.join("|");
+  const match = normalized.match(
+    new RegExp(`^(${typePattern})\\((#[0-9]+|F[0-9]{3,})\\):\\s+\\S.+$`, "i")
+  );
+  if (!match) return false;
+  return match[2].toLowerCase() === normalizedScope.toLowerCase();
+}
 function isSameOrWithin2(parentDir, candidatePath) {
   const relative = path8.relative(parentDir, candidatePath);
   return relative === "" || relative !== ".." && !relative.startsWith(`..${path8.sep}`) && !path8.isAbsolute(relative);
@@ -7591,7 +7651,8 @@ function isPrePrEvidenceSatisfied(check) {
 }
 var BRANCH_LABELS2 = ["Branch", "\uBE0C\uB79C\uCE58"];
 function resolveLocalCompletionStrategy(config) {
-  return config.workflow?.completionStrategy === "local-ff" ? "local-ff" : "none";
+  const strategy = config.workflow?.completionStrategy;
+  return strategy === "local-ff" || strategy === "local-squash" ? strategy : "none";
 }
 async function resolveLocalIntegrationContext(config, feature) {
   const projectRoot = resolveProjectRoot(config, feature);
@@ -7611,6 +7672,9 @@ async function resolveLocalIntegrationContext(config, feature) {
     );
   }
   const state = await readLocalIntegrationState(projectRoot, feature);
+  const configuredStrategy = resolveLocalCompletionStrategy(config);
+  const completionStrategy = configuredStrategy === "local-squash" ? "local-squash" : "local-ff";
+  const evidenceRef = resolveEvidenceRef(feature);
   const featureBranchTip = resolveRef(
     projectRoot,
     `refs/heads/${featureBranch}`
@@ -7624,6 +7688,14 @@ async function resolveLocalIntegrationContext(config, feature) {
   );
   const managedFeatureWorktree = !!registeredWorktree && path8.resolve(registeredWorktree) !== path8.resolve(projectRoot);
   const effectiveFeatureWorktree = registeredWorktree || (fs.existsSync(featureWorktree) ? featureWorktree : projectRoot);
+  const baseContainsFeature = !!featureTip && !!baseTip && isAncestor(projectRoot, featureTip, `refs/heads/${baseBranch}`);
+  const integratedCommit = state?.integratedCommit || state?.mergedBaseTip;
+  const evidenceTip = resolveRef(projectRoot, evidenceRef);
+  const featureTree = featureTip ? resolveTree(projectRoot, featureTip) : null;
+  const integratedTree = integratedCommit ? resolveTree(projectRoot, integratedCommit) : null;
+  const squashCommitMatchesSource = completionStrategy === "local-squash" && state?.strategy === "local-squash" && !!featureTip && state.featureTip === featureTip && !!integratedCommit && !!baseTip && isAncestor(projectRoot, integratedCommit, `refs/heads/${baseBranch}`) && !!featureTree && integratedTree === featureTree && state.integratedTree === featureTree;
+  const squashEvidencePresent = !!featureTip && evidenceTip === featureTip;
+  const squashIntegrationComplete = squashCommitMatchesSource && squashEvidencePresent;
   return {
     projectRoot,
     featureWorktree: effectiveFeatureWorktree,
@@ -7634,7 +7706,12 @@ async function resolveLocalIntegrationContext(config, feature) {
     baseTip,
     currentBranch,
     state,
-    baseContainsFeature: !!featureTip && !!baseTip && isAncestor(projectRoot, featureTip, `refs/heads/${baseBranch}`),
+    completionStrategy,
+    baseContainsFeature,
+    integrationComplete: completionStrategy === "local-squash" ? squashIntegrationComplete : baseContainsFeature,
+    evidenceRef,
+    squashCommitMatchesSource,
+    squashEvidencePresent,
     projectRootClean: isClean(projectRoot),
     featureWorktreeClean: isClean(effectiveFeatureWorktree),
     docsClean: isClean(feature.git.docsGitCwd),
@@ -7663,7 +7740,7 @@ async function readLocalIntegrationState(projectRoot, feature) {
   }
 }
 function localCleanupComplete(context) {
-  return context.baseContainsFeature && context.currentBranch === context.baseBranch && !context.managedFeatureWorktree && (!context.deleteFeatureBranchAfterMerge || !context.featureBranchExists) && context.projectRootClean && context.docsClean && context.state?.status === "cleaned" && context.state.featureTip === context.featureTip && context.state.mergedBaseTip === context.baseTip;
+  return context.integrationComplete && context.currentBranch === context.baseBranch && !context.managedFeatureWorktree && (!context.deleteFeatureBranchAfterMerge || !context.featureBranchExists) && context.projectRootClean && context.docsClean && context.state?.status === "cleaned" && context.state.featureTip === context.featureTip && context.state.mergedBaseTip === context.baseTip;
 }
 function runPostMergeChecks(projectRoot, checks) {
   const results = [];
@@ -7688,6 +7765,12 @@ function currentGitBranch(cwd) {
 function resolveRef(cwd, ref) {
   return runGitCapture(["rev-parse", "--verify", ref], cwd) || null;
 }
+function resolveTree(cwd, commit) {
+  return resolveRef(cwd, `${commit}^{tree}`);
+}
+function preserveLocalIntegrationEvidence(projectRoot, evidenceRef, featureTip) {
+  return gitRun(projectRoot, ["update-ref", evidenceRef, featureTip]);
+}
 function isAncestor(cwd, ancestor, descendant) {
   return runProcess(
     "git",
@@ -7711,7 +7794,7 @@ function resolveProjectRoot(config, feature) {
 function resolveStatePath(projectRoot, feature) {
   const commonDirRaw = runGitCapture(["rev-parse", "--git-common-dir"], projectRoot) || ".git";
   const commonDir = path8.isAbsolute(commonDirRaw) ? commonDirRaw : path8.resolve(projectRoot, commonDirRaw);
-  const key = crypto.createHash("sha256").update(`${feature.type}:${feature.folderName}`).digest("hex").slice(0, 24);
+  const key = resolveFeatureStateKey(feature);
   return path8.join(
     commonDir,
     "lee-spec-kit",
@@ -7719,6 +7802,12 @@ function resolveStatePath(projectRoot, feature) {
     `${key}.json`
   );
 }
+function resolveEvidenceRef(feature) {
+  return `refs/lee-spec-kit/integrations/${resolveFeatureStateKey(feature)}`;
+}
+function resolveFeatureStateKey(feature) {
+  return crypto.createHash("sha256").update(`${feature.type}:${feature.folderName}`).digest("hex").slice(0, 24);
+}
 async function readTasks(featureDir) {
   const tasksPath = path8.join(featureDir, "tasks.md");
   return await fs.pathExists(tasksPath) ? fs.readFile(tasksPath, "utf-8") : "";
@@ -8116,8 +8205,13 @@ function resolveProjectCommitTopic(feature, tasks) {
 }
 function buildTaskCommitSummary(input) {
   const { feature, tasks, effectiveProjectGitCwd, docsDirty, projectDirty, gateFailureReason } = input;
-  const docsMessage = tasks.issueNumber ? `git -C "${feature.git.docsGitCwd}" add "${feature.docs.featurePathFromDocs}" && git -C "${feature.git.docsGitCwd}" commit -m "docs(#${tasks.issueNumber}): ${feature.folderName} \uBB38\uC11C \uC5C5\uB370\uC774\uD2B8"` : `git -C "${feature.git.docsGitCwd}" add "${feature.docs.featurePathFromDocs}" && git -C "${feature.git.docsGitCwd}" commit -m "docs: ${feature.folderName} \uBB38\uC11C \uC5C5\uB370\uC774\uD2B8"`;
-  const projectMessage = tasks.issueNumber ? `Stage only the files touched by the just-finished task in "${effectiveProjectGitCwd}", then commit with: git -C "${effectiveProjectGitCwd}" commit -m "feat(#${tasks.issueNumber}): ${resolveProjectCommitTopic(feature, tasks)}"` : `Stage only the files touched by the just-finished task in "${effectiveProjectGitCwd}", then commit with: git -C "${effectiveProjectGitCwd}" commit -m "feat(${feature.folderName}): ${resolveProjectCommitTopic(feature, tasks)}"`;
+  const scope = resolveFeatureCommitScope({
+    issueNumber: tasks.issueNumber,
+    featureId: feature.id,
+    workflowMode: tasks.issueNumber ? "github" : "local"
+  }) || feature.id;
+  const docsMessage = `git -C "${feature.git.docsGitCwd}" add "${feature.docs.featurePathFromDocs}" && git -C "${feature.git.docsGitCwd}" commit -m "docs(${scope}): ${feature.folderName} \uBB38\uC11C \uC5C5\uB370\uC774\uD2B8"`;
+  const projectMessage = `Stage only the files touched by the just-finished task in "${effectiveProjectGitCwd}", then commit with: git -C "${effectiveProjectGitCwd}" commit -m "feat(${scope}): ${resolveProjectCommitTopic(feature, tasks)}"`;
   const lines = ["Finish the task-level commit checkpoint before continuing."];
   if (gateFailureReason) {
     lines.push(`Current gate failure: ${gateFailureReason}`);
@@ -8987,11 +9081,13 @@ Task commit boundary warning: ${describeTaskCommitGateFailure(committedTaskGate)
       "implementation_approve",
       true
     );
-    const localIntegrationApproval = config.workflow?.mode === "local" && resolveLocalCompletionStrategy(config) === "local-ff";
+    const localIntegrationApproval = config.workflow?.mode === "local" && resolveLocalCompletionStrategy(config) !== "none";
+    const separateLocalMergeApproval = localIntegrationApproval && resolveActionApprovalRequired(config, "local_merge", false);
     const localBaseBranch = config.workflow?.baseBranch?.trim() || "main";
+    const localIntegrationLabel = resolveLocalCompletionStrategy(config) === "local-squash" ? `squash integration into ${localBaseBranch}` : `fast-forward integration into ${localBaseBranch}`;
     const localCleanupSummary = config.workflow?.deleteFeatureBranchAfterMerge === false ? "remove any managed Feature worktree" : "remove any managed Feature worktree and delete the integrated local Feature branch";
     const actionOptions = approvalRequired ? buildApprovalActionOptions({
-      approveSummary: localIntegrationApproval ? `Approve the completed implementation and authorize fast-forward integration into ${localBaseBranch}, post-merge verification, and cleanup that will ${localCleanupSummary}.` : "Approve the completed implementation and continue to the pre-PR or PR preparation stage.",
+      approveSummary: separateLocalMergeApproval ? `Approve the completed implementation and continue to the separate local merge approval before ${localIntegrationLabel}.` : localIntegrationApproval ? `Approve the completed implementation and authorize ${localIntegrationLabel}, post-merge verification, and cleanup that will ${localCleanupSummary}.` : "Approve the completed implementation and continue to the pre-PR or PR preparation stage.",
       holdSummary: "Request implementation changes before the workflow continues."
     }) : void 0;
     return {
@@ -9002,7 +9098,7 @@ Task commit boundary warning: ${describeTaskCommitGateFailure(committedTaskGate)
       stage: "implementation_approve",
       nextAction: buildAction(
         "implementation_approve",
-        localIntegrationApproval ? `Share the completed implementation and get user approval for the remaining local completion flow: fast-forward into ${localBaseBranch}, run post-merge checks, then ${localCleanupSummary}. Record that approval in tasks.md.` : "Share the completed implementation, get user approval, and record the completion checkpoint in tasks.md.",
+        separateLocalMergeApproval ? `Share the completed implementation and get user approval for the implementation itself. Record it in tasks.md; ${localIntegrationLabel} will require a separate local_merge approval.` : localIntegrationApproval ? `Share the completed implementation and get user approval for the remaining local completion flow: ${localIntegrationLabel}, run post-merge checks, then ${localCleanupSummary}. Record that approval in tasks.md.` : "Share the completed implementation, get user approval, and record the completion checkpoint in tasks.md.",
         approvalRequired
       ),
       approvalRequired,
@@ -9031,10 +9127,10 @@ Task commit boundary warning: ${describeTaskCommitGateFailure(committedTaskGate)
       blockedReasonCode: "PRE_PR_REVIEW_NOT_APPROVED"
     };
   }
-  if (config.workflow?.mode === "local" && resolveLocalCompletionStrategy(config) === "local-ff") {
+  if (config.workflow?.mode === "local" && resolveLocalCompletionStrategy(config) !== "none") {
     const localState = await resolveLocalIntegrationContext(config, feature);
     const localMergeBaseCommand = `npx lee-spec-kit local merge ${buildFeatureArgs(feature)} --json`;
-    if (!localState.baseContainsFeature) {
+    if (!localState.integrationComplete) {
       const approvalRequired = resolveActionApprovalRequired(
         config,
         "local_merge",
@@ -9042,7 +9138,7 @@ Task commit boundary warning: ${describeTaskCommitGateFailure(committedTaskGate)
       );
       const command = approvalRequired ? `${localMergeBaseCommand} --confirm OK` : localMergeBaseCommand;
       const actionOptions = approvalRequired ? buildApprovalActionOptions({
-        approveSummary: `Fast-forward ${localState.featureBranch} into ${localState.baseBranch} and run the configured post-merge checks.`,
+        approveSummary: localState.completionStrategy === "local-squash" ? `Squash ${localState.featureBranch} into ${localState.baseBranch}, preserve the source Feature tip, and run the configured post-merge checks.` : `Fast-forward ${localState.featureBranch} into ${localState.baseBranch} and run the configured post-merge checks.`,
         holdSummary: "Keep the completed Feature branch unmerged for now."
       }) : void 0;
       return {
@@ -9053,7 +9149,7 @@ Task commit boundary warning: ${describeTaskCommitGateFailure(committedTaskGate)
         stage: "local_merge",
         nextAction: buildAction(
           "local_merge",
-          `Fast-forward ${localState.featureBranch} into ${localState.baseBranch}; do not create a merge commit.`,
+          localState.completionStrategy === "local-squash" ? `Create one squash commit from ${localState.featureBranch} on ${localState.baseBranch} and preserve the source Feature tip as internal integration evidence.` : `Fast-forward ${localState.featureBranch} into ${localState.baseBranch}; do not create a merge commit.`,
           approvalRequired,
           command
         ),
@@ -9991,35 +10087,21 @@ var DEFAULT_MANAGED_DOC_FILES = [
   ".gitignore"
 ];
 
-// src/utils/commit-conventions.ts
-var PROJECT_COMMIT_PREFIX_PATTERN = /^(feat|fix|refactor|test|chore)\(#(\d+)\):\s+\S.+$/i;
-var DOCS_COMMIT_PREFIX_PATTERN = /^docs\(#(\d+)\):\s+\S.+$/i;
-function matchesProjectCommitConvention(message, issueNumber) {
-  const normalized = String(message || "").trim();
-  if (!normalized) return false;
-  const match = normalized.match(PROJECT_COMMIT_PREFIX_PATTERN);
-  if (!match) return false;
-  return Number(match[2]) === issueNumber;
-}
-function matchesDocsCommitConvention(message, issueNumber) {
-  const normalized = String(message || "").trim();
-  if (!normalized) return false;
-  const match = normalized.match(DOCS_COMMIT_PREFIX_PATTERN);
-  if (!match) return false;
-  return Number(match[1]) === issueNumber;
-}
-
 // src/commands/commit-audit.ts
 var CANONICAL_FEATURE_DOC_PATTERN = /^features\/(?:[^/]+\/)?F\d{3,}[^/]*\/(spec|plan|tasks|decisions|issue|pr)\.md$/i;
 var FEATURE_DOC_CANDIDATE_PATTERN = /^features\/(?:[^/]+\/)?F\d{3,}[^/]*\/(.+)$/i;
 function commitAuditCommand(program2) {
-  program2.command("commit-audit").description("Validate staged docs paths before commit").option("--json", "Output JSON for hooks and agents").option("--git-root <path>", "Override the git root used for staged-path inspection").option("--message <message>", "Validate a commit subject against the current workflow convention").action(async (options) => {
+  program2.command("commit-audit").description("Validate staged docs paths and canonical commit subjects before commit").option("--json", "Output JSON for hooks and agents").option("--git-root <path>", "Override the git root used for staged-path inspection").option("--message <message>", "Validate a commit subject against the current workflow convention").option("--message-file <path>", "Read and validate the commit subject from a commit message file").option("--enforce", "Exit non-zero when commit-audit blocks the commit").action(async (options) => {
     try {
+      const commitMessage = await resolveCommitMessageInput(process.cwd(), options);
       const payload = await collectCommitAudit(
         process.cwd(),
         options.gitRoot,
-        options.message
+        commitMessage
       );
+      if (options.enforce && payload.status === "blocked") {
+        process.exitCode = 1;
+      }
       if (options.json) {
         console.log(JSON.stringify(payload, null, 2));
         return;
@@ -10046,6 +10128,7 @@ function commitAuditCommand(program2) {
             2
           )
         );
+        if (options.enforce) process.exitCode = 1;
         return;
       }
       process.stderr.write(`[${cliError.code}] ${cliError.message}
@@ -10054,6 +10137,18 @@ function commitAuditCommand(program2) {
     }
   });
 }
+async function resolveCommitMessageInput(cwd, options) {
+  if (options.message && options.messageFile) {
+    throw createCliError(
+      "INVALID_ARGUMENT",
+      "Use either --message or --message-file, not both."
+    );
+  }
+  if (options.message) return options.message;
+  if (!options.messageFile) return void 0;
+  const content = await fs26.readFile(path8.resolve(cwd, options.messageFile), "utf-8");
+  return content.split(/\r?\n/u).map((line) => line.trim()).find((line) => line.length > 0 && !line.startsWith("#"));
+}
 async function collectCommitAudit(cwd, gitRootOverride, commitMessage) {
   const config = await getConfig(cwd);
   if (!config) {
@@ -10277,10 +10372,17 @@ async function collectCommitMessageViolation(cwd, config, repoRoot, stagedEntrie
     return null;
   }
   const selection = await resolveFeatureSelection(cwd);
-  if (selection.status !== "selected" || !selection.matchedFeature?.issueNumber) {
+  if (selection.status !== "selected" || !selection.matchedFeature) {
+    return null;
+  }
+  const scope = resolveFeatureCommitScope({
+    issueNumber: selection.matchedFeature.issueNumber,
+    featureId: selection.matchedFeature.id,
+    workflowMode: config.workflow?.mode
+  });
+  if (!scope) {
     return null;
   }
-  const issueNumber = selection.matchedFeature.issueNumber;
   const docsRepoRoot = runGitCapture(["rev-parse", "--show-toplevel"], config.docsDir);
   const normalizedRepoRoot = path8.resolve(repoRoot);
   const normalizedDocsRepoRoot = docsRepoRoot ? path8.resolve(docsRepoRoot) : null;
@@ -10290,15 +10392,15 @@ async function collectCommitMessageViolation(cwd, config, repoRoot, stagedEntrie
     return !!relativeToDocs && relativeToDocs !== "" && !relativeToDocs.startsWith("..");
   });
   const isDocsCommit = !!normalizedDocsRepoRoot && normalizedDocsRepoRoot === normalizedRepoRoot && (config.docsRepo === "standalone" || docsOnlyCommit);
-  const valid = isDocsCommit ? matchesDocsCommitConvention(normalizedMessage, issueNumber) : matchesProjectCommitConvention(normalizedMessage, issueNumber);
+  const valid = isDocsCommit ? matchesDocsCommitConvention(normalizedMessage, scope) : matchesProjectCommitConvention(normalizedMessage, scope);
   if (valid) {
     return null;
   }
-  const expected = isDocsCommit ? `docs(#${issueNumber}): ...` : `type(#${issueNumber}): ... (feat/fix/refactor/test/chore)`;
+  const expected = isDocsCommit ? `docs(${scope}): ...` : `type(${scope}): ... (feat/fix/refactor/test/style/chore)`;
   return {
     path: "(commit message)",
     kind: "commit_message_policy",
-    detail: `Commit subject must follow the issue-scoped convention for this feature. Expected ${expected}, received "${normalizedMessage}".`
+    detail: `Commit subject must follow the canonical feature-scoped convention. Expected ${expected}, received "${normalizedMessage}".`
   };
 }
 function normalizeEntryName(value) {
@@ -10609,7 +10711,7 @@ async function collectDocsAudit(cwd) {
 // src/commands/local.ts
 function localCommand(program2) {
   const local = program2.command("local").description("Integrate and clean up local workflow feature branches");
-  local.command("merge [feature-name]").description("Fast-forward a completed local feature and verify the result").option("--component <component>", "Component name for multi projects").option(
+  local.command("merge [feature-name]").description("Integrate a completed local feature and verify the result").option("--component <component>", "Component name for multi projects").option(
     "--confirm <token>",
     "Approval token when local_merge requires approval"
   ).option("--json", "Output JSON for agents and hooks").action(
@@ -10708,7 +10810,8 @@ async function runLocalMerge(featureName, options) {
     );
   }
   const now = (/* @__PURE__ */ new Date()).toISOString();
-  let state = context.state || {
+  const previousStateStrategy = context.state?.strategy || "local-ff";
+  let state = context.state && context.state.featureTip === context.featureTip && previousStateStrategy === context.completionStrategy ? context.state : {
     version: 1,
     featureRef: feature.folderName,
     component: feature.type,
@@ -10716,20 +10819,39 @@ async function runLocalMerge(featureName, options) {
     featureBranch: context.featureBranch,
     featureTip: context.featureTip,
     mergedBaseTip: context.baseTip,
+    strategy: context.completionStrategy,
     status: "merged",
     mergedAt: now,
     verifiedAt: null,
     cleanedAt: null,
     verification: []
   };
-  if (!context.baseContainsFeature) {
+  if (context.completionStrategy === "local-squash" && context.squashCommitMatchesSource && !context.squashEvidencePresent) {
+    const evidence = preserveLocalIntegrationEvidence(
+      context.projectRoot,
+      context.evidenceRef,
+      context.featureTip
+    );
+    if (evidence.code !== 0) {
+      return blocked(
+        "LOCAL_SQUASH_EVIDENCE_FAILED",
+        feature.folderName,
+        evidence.stderr
+      );
+    }
+    context = await resolveLocalIntegrationContext(config, feature);
+  }
+  if (!context.featureTip || !context.baseTip) {
+    return blocked("LOCAL_MERGE_REF_NOT_FOUND", feature.folderName);
+  }
+  if (!context.integrationComplete) {
     if (!isAncestor(
       context.projectRoot,
       `refs/heads/${context.baseBranch}`,
       context.featureTip
     )) {
       return blocked(
-        "LOCAL_MERGE_NOT_FAST_FORWARD",
+        context.completionStrategy === "local-squash" ? "LOCAL_SQUASH_BASE_NOT_ANCESTOR" : "LOCAL_MERGE_NOT_FAST_FORWARD",
         feature.folderName,
         `${context.baseBranch} is not an ancestor of ${context.featureBranch}.`
       );
@@ -10747,26 +10869,21 @@ async function runLocalMerge(featureName, options) {
         );
       }
     }
-    const merge = gitRun(context.projectRoot, [
-      "merge",
-      "--ff-only",
-      context.featureBranch
-    ]);
-    if (merge.code !== 0) {
-      return blocked(
-        "LOCAL_MERGE_NOT_FAST_FORWARD",
-        feature.folderName,
-        merge.stderr
-      );
-    }
+    const integration = context.completionStrategy === "local-squash" ? integrateLocalSquash(context, feature.folderName, feature.id, feature.slug) : integrateLocalFastForward(context, feature.folderName);
+    if (integration.status !== "ok") return integration.payload;
     const mergedBaseTip = resolveRef(
       context.projectRoot,
       `refs/heads/${context.baseBranch}`
     );
+    const integratedTree = mergedBaseTip ? resolveTree(context.projectRoot, mergedBaseTip) : null;
     state = {
       ...state,
       featureTip: context.featureTip,
       mergedBaseTip: mergedBaseTip || context.featureTip,
+      strategy: context.completionStrategy,
+      integratedCommit: mergedBaseTip || context.featureTip,
+      ...integratedTree ? { integratedTree } : {},
+      ...context.completionStrategy === "local-squash" ? { evidenceRef: context.evidenceRef } : {},
       status: "merged",
       mergedAt: now,
       verifiedAt: null,
@@ -10776,7 +10893,7 @@ async function runLocalMerge(featureName, options) {
     await writeLocalIntegrationState(context.projectRoot, feature, state);
     context = await resolveLocalIntegrationContext(config, feature);
   }
-  if (!context.baseContainsFeature) {
+  if (!context.integrationComplete) {
     return blocked("LOCAL_MERGE_VERIFICATION_FAILED", feature.folderName);
   }
   const verification = runPostMergeChecks(
@@ -10825,6 +10942,7 @@ async function runLocalMerge(featureName, options) {
     featureBranch: context.featureBranch,
     featureTip: context.featureTip,
     baseTip,
+    completionStrategy: context.completionStrategy,
     verification
   };
 }
@@ -10855,7 +10973,7 @@ async function runLocalCleanup(featureName, options) {
   }
   const feature = selection.matchedFeature;
   let context = await resolveLocalIntegrationContext(config, feature);
-  if (!context.baseContainsFeature || !context.state || !["verified", "cleaned"].includes(context.state.status) || context.state.featureTip !== context.featureTip || context.state.mergedBaseTip !== context.baseTip) {
+  if (!context.integrationComplete || !context.state || !["verified", "cleaned"].includes(context.state.status) || context.state.featureTip !== context.featureTip || context.state.mergedBaseTip !== context.baseTip) {
     return blocked("LOCAL_MERGE_NOT_VERIFIED", feature.folderName);
   }
   if (!context.featureWorktreeClean || !context.projectRootClean || !context.docsClean) {
@@ -10881,7 +10999,7 @@ async function runLocalCleanup(featureName, options) {
   if (context.deleteFeatureBranchAfterMerge && context.featureBranchExists) {
     const removeBranch = gitRun(context.projectRoot, [
       "branch",
-      "-d",
+      context.completionStrategy === "local-squash" ? "-D" : "-d",
       context.featureBranch
     ]);
     if (removeBranch.code !== 0) {
@@ -10905,9 +11023,106 @@ async function runLocalCleanup(featureName, options) {
     baseBranch: context.baseBranch,
     featureBranch: context.featureBranch,
     featureTip: context.featureTip,
-    baseTip: context.baseTip
+    baseTip: context.baseTip,
+    completionStrategy: context.completionStrategy
   };
 }
+function integrateLocalFastForward(context, featureRef) {
+  const merge = gitRun(context.projectRoot, [
+    "merge",
+    "--ff-only",
+    context.featureBranch
+  ]);
+  if (merge.code !== 0) {
+    return {
+      status: "blocked",
+      payload: blocked(
+        "LOCAL_MERGE_NOT_FAST_FORWARD",
+        featureRef,
+        merge.stderr
+      )
+    };
+  }
+  return { status: "ok" };
+}
+function integrateLocalSquash(context, featureRef, featureId, featureSlug) {
+  const originalBaseTip = context.baseTip;
+  if (!originalBaseTip || !context.featureTip) {
+    return {
+      status: "blocked",
+      payload: blocked("LOCAL_MERGE_REF_NOT_FOUND", featureRef)
+    };
+  }
+  const squash = gitRun(context.projectRoot, [
+    "merge",
+    "--squash",
+    context.featureBranch
+  ]);
+  if (squash.code !== 0) {
+    rollbackSquash(context.projectRoot, originalBaseTip);
+    return {
+      status: "blocked",
+      payload: blocked("LOCAL_SQUASH_FAILED", featureRef, squash.stderr)
+    };
+  }
+  const scope = resolveFeatureCommitScope({
+    featureId,
+    workflowMode: "local"
+  });
+  if (!scope) {
+    rollbackSquash(context.projectRoot, originalBaseTip);
+    return {
+      status: "blocked",
+      payload: blocked(
+        "LOCAL_SQUASH_COMMIT_SCOPE_INVALID",
+        featureRef,
+        `Could not resolve a canonical local commit scope from ${featureId}.`
+      )
+    };
+  }
+  const commit = gitRun(context.projectRoot, [
+    "commit",
+    "-m",
+    `feat(${scope}): integrate ${featureSlug}`
+  ]);
+  if (commit.code !== 0) {
+    rollbackSquash(context.projectRoot, originalBaseTip);
+    return {
+      status: "blocked",
+      payload: blocked("LOCAL_SQUASH_COMMIT_FAILED", featureRef, commit.stderr)
+    };
+  }
+  const integratedCommit = resolveRef(context.projectRoot, "HEAD");
+  const sourceTree = resolveTree(context.projectRoot, context.featureTip);
+  const integratedTree = integratedCommit ? resolveTree(context.projectRoot, integratedCommit) : null;
+  if (!integratedCommit || !sourceTree || integratedTree !== sourceTree) {
+    rollbackSquash(context.projectRoot, originalBaseTip);
+    return {
+      status: "blocked",
+      payload: blocked("LOCAL_SQUASH_TREE_MISMATCH", featureRef)
+    };
+  }
+  const evidence = preserveLocalIntegrationEvidence(
+    context.projectRoot,
+    context.evidenceRef,
+    context.featureTip
+  );
+  if (evidence.code !== 0) {
+    rollbackSquash(context.projectRoot, originalBaseTip);
+    return {
+      status: "blocked",
+      payload: blocked(
+        "LOCAL_SQUASH_EVIDENCE_FAILED",
+        featureRef,
+        evidence.stderr
+      )
+    };
+  }
+  return { status: "ok" };
+}
+function rollbackSquash(projectRoot, originalBaseTip) {
+  gitRun(projectRoot, ["reset", "--hard", originalBaseTip]);
+}
 function blocked(reasonCode, featureRef, error) {
   return {
     status: "blocked",