@bytesbrains/pi-contrib-gate 1.6.1

package/src/tools/propose.ts

@@ -0,0 +1,120 @@
+import { Type } from "typebox";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "../config";
+import { exec, currentBranch, getStagedStats, countUnrelatedDirs, shellEscape, getLinkedIssueId } from "../helpers";
+import { validateBranchName, validateConventionalCommit, runQualityGate } from "../validate";
+
+export const proposeTool = {
+  name: "contrib_propose" as const,
+  label: "Propose Changes",
+  description: "Stage files, validate conventional commit, run quality checks, and commit.",
+  parameters: Type.Object({
+    message: Type.String({ description: "Conventional commit message: type(scope): subject" }),
+    body: Type.Optional(Type.String({ description: "Extended commit body with details" })),
+  }),
+  async execute(_toolCallId: string, params: any, _signal: any, _onUpdate: any, ctx: ExtensionContext) {
+    const config = loadConfig(ctx.cwd);
+    const branch = currentBranch(ctx.cwd);
+
+    // ── Require a linked issue ──
+    const issueId = getLinkedIssueId(ctx.cwd);
+    if (!issueId) {
+      return {
+        content: [{
+          type: "text",
+          text: [
+            `❌ No Gitea issue linked.`,
+            ``,
+            `Before committing, link your work to an issue with:`,
+            `  contrib_start_work(issue_id)`,
+            ``,
+            `This ensures commits and PRs are traceable to the correct issue.`,
+          ].join("\n"),
+        }],
+        isError: true,
+        details: {},
+      };
+    }
+
+    const branchCheck = validateBranchName(branch);
+    if (!branchCheck.ok) return { content: [{ type: "text", text: branchCheck.error }], isError: true, details: {} };
+
+    if (config.commits.convention === "conventional") {
+      const msgCheck = validateConventionalCommit(params.message, config);
+      if (!msgCheck.ok) return { content: [{ type: "text", text: msgCheck.error }], isError: true, details: {} };
+    }
+
+    const add = exec("git add -A", ctx.cwd);
+    if (!add.ok) return { content: [{ type: "text", text: `Failed to stage files: ${add.stderr}` }], isError: true, details: {} };
+
+    const quality = runQualityGate(ctx.cwd, config);
+    if (!quality.ok) {
+      return { content: [{ type: "text", text: `❌ Quality gate failed:\n\n${quality.errors.map((e: string) => `  - ${e}`).join("\n")}` }], isError: true, details: { errors: quality.errors } };
+    }
+
+    // ── Best-practice soft warnings (non-blocking) ──
+    const bestPractices = config.commits.bestPractices;
+    const warnings: string[] = [];
+
+    if (bestPractices.maxLinesPerCommit > 0) {
+      const { linesAdded } = getStagedStats(ctx.cwd);
+      if (linesAdded > bestPractices.maxLinesPerCommit) {
+        warnings.push(
+          `⚠️  Commit size (${linesAdded} lines) exceeds best-practice threshold (${bestPractices.maxLinesPerCommit} lines).`,
+          `    Consider splitting into smaller, more frequent commits.`,
+        );
+      }
+    }
+
+    if (bestPractices.requireAtomic) {
+      const { files } = getStagedStats(ctx.cwd);
+      const dirCount = countUnrelatedDirs(files);
+      if (dirCount > bestPractices.maxUnrelatedDirs) {
+        warnings.push(
+          `⚠️  This commit touches ${dirCount} unrelated directories (threshold: ${bestPractices.maxUnrelatedDirs}).`,
+          `    It may not be atomic. Each commit should do one logical thing.`,
+        );
+      }
+    }
+
+    let fullMessage = params.message;
+    if (params.body) fullMessage += `\n\n${params.body}`;
+    if (issueId) fullMessage += `\n\nRefs: #${issueId}`;
+
+    const commit = exec(`git commit -m ${shellEscape(fullMessage)}`, ctx.cwd);
+    if (!commit.ok) return { content: [{ type: "text", text: `Commit failed: ${commit.stderr}` }], isError: true, details: {} };
+
+    const hash = exec("git rev-parse HEAD", ctx.cwd).stdout.slice(0, 8);
+    (globalThis as any).__contrib_lastHash = hash;
+
+    // Build output message with best-practice guidance and warnings
+    const outputLines: string[] = [
+      `✅ Changes committed (${hash})`,
+      `   Branch: ${branch}`,
+      `   Message: ${params.message}`,
+    ];
+
+    // Inject best-practice guidance when enabled
+    if (bestPractices.shortFrequentCommits && bestPractices.guidanceText.length > 0) {
+      outputLines.push(``, `📋 Best Practice Guidance:`);
+      for (const line of bestPractices.guidanceText) {
+        outputLines.push(`   • ${line}`);
+      }
+    }
+
+    // Append soft warnings
+    if (warnings.length > 0) {
+      outputLines.push(``, `--- Soft Warnings (non-blocking) ---`);
+      for (const w of warnings) {
+        outputLines.push(w);
+      }
+    }
+
+    outputLines.push(``, `Next: contrib_submit(title, body) to push and create PR.`);
+
+    return {
+      content: [{ type: "text", text: outputLines.join("\n") }],
+      details: { branch, commit: hash, message: params.message, warnings: warnings.length > 0 ? warnings : undefined },
+    };
+  },
+};

package/src/tools/start_work.ts

@@ -0,0 +1,242 @@
+import { Type } from "typebox";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { loadConfig } from "../config";
+import { exec, isClean, shellEscape, getLinkedIssueId, remoteBranchExists, checkBranchPRState, resolveGitea, giteaApi } from "../helpers";
+
+export const startWorkTool = {
+  name: "contrib_start_work" as const,
+  label: "Start Work",
+  description: "Link work to a Gitea issue. Creates a feature branch if not already on one; otherwise links the issue to the current branch (e.g., for rework on an existing PR).",
+  parameters: Type.Object({
+    issue_id: Type.String({ description: "Issue number or ID to link this work to" }),
+    type: Type.Optional(Type.String({ description: "Branch type: feat, fix, or chore (default: feat)" })),
+  }),
+  async execute(_toolCallId: string, params: any, _signal: any, _onUpdate: any, ctx: ExtensionContext) {
+    const config = loadConfig(ctx.cwd);
+    const branchType = params.type || "feat";
+    const issueId = params.issue_id.replace(/^#/, "");
+    const currentBr = exec("git branch --show-current", ctx.cwd).stdout;
+    const isFeatureBranch = /^(feat|fix|chore)\//.test(currentBr);
+
+    if (!["feat", "fix", "chore"].includes(branchType)) {
+      return { content: [{ type: "text", text: `Invalid branch type: "${branchType}". Use: feat, fix, or chore.` }], isError: true, details: {} };
+    }
+
+    // ── Validate issue exists on Gitea ──
+    if (config.requireIssueValidation) {
+      const opts = resolveGitea(ctx.cwd);
+      if (!opts.repo) {
+        return {
+          content: [{
+            type: "text",
+            text: [
+              `⚠️  Could not resolve Gitea repo to validate issue #${issueId}.`,
+              ``,
+              `Set requireIssueValidation: false in .contribrc.yml to skip validation.`,
+            ].join("\n"),
+          }],
+          isError: true,
+          details: { issueId },
+        };
+      }
+
+      const r = await giteaApi(`/issues/${issueId}`, "GET", null, opts);
+      if (!r.ok || !r.data) {
+        return {
+          content: [{
+            type: "text",
+            text: [
+              `❌ Issue #${issueId} does not exist on Gitea.`,
+              ``,
+              `You must link work to a real Gitea issue.`,
+              `Use project_list_issues() to see available issues,`,
+              `or project_create_issue() to create a new one.`,
+            ].join("\n"),
+          }],
+          isError: true,
+          details: { issueId },
+        };
+      }
+
+      const issue = r.data as Record<string, unknown>;
+      const issueTitle = issue.title || "(no title)";
+      const issueState = issue.state || "unknown";
+      const issueAssignee = (issue.assignee as any)?.login || "";
+      const issueLabels = Array.isArray(issue.labels) ? (issue.labels as any[]).map((l: any) => l.name).join(", ") : "";
+
+      const warnings: string[] = [];
+
+      // Block: issue is closed
+      if (issueState !== "open") {
+        return {
+          content: [{
+            type: "text",
+            text: [
+              `❌ Issue #${issueId} is ${issueState}: "${issueTitle}"`,
+              ``,
+              `Cannot start work on a ${issueState} issue.`,
+              `Reopen the issue first or pick an open one: project_list_issues().`,
+            ].join("\n"),
+          }],
+          isError: true,
+          details: { issueId, state: issueState, title: issueTitle },
+        };
+      }
+
+      // Warn: assigned to someone else
+      if (issueAssignee && issueAssignee !== "factory") {
+        warnings.push(`⚠️  Issue #${issueId} is assigned to "${issueAssignee}". Verify you should be working on this.`);
+      }
+
+      // Build the output prefix with issue context so agent can verify relevance
+      const issueInfo = [
+        `📋 Issue #${issueId}: "${issueTitle}"`,
+        `   State: ${issueState}${issueLabels ? ` | Labels: ${issueLabels}` : ""}${issueAssignee ? ` | Assignee: ${issueAssignee}` : ""}`,
+      ];
+
+      if (warnings.length > 0) {
+        issueInfo.push("");
+        for (const w of warnings) issueInfo.push(w);
+      }
+
+      // ── Now proceed with branch handling ──
+
+      // ═══ Case 1: Already on a feature branch ═══
+      if (isFeatureBranch) {
+        const remote = remoteBranchExists(ctx.cwd);
+        if (!remote.exists) {
+          const pr = await checkBranchPRState(ctx.cwd);
+          const prNote = pr
+            ? `\n\nPR ${pr.url} was ${pr.state === "merged" ? "already merged" : "closed"}.`
+            : "";
+          return {
+            content: [{
+              type: "text",
+              text: [
+                ...issueInfo,
+                "",
+                `⚠️  Branch "${currentBr}" has no remote — the PR was likely merged.`,
+                `${prNote}`,
+                ``,
+                `Continuing work on this branch risks creating orphaned commits.`,
+                ``,
+                `Recommended: start fresh work on a new branch:`,
+                `  git checkout main`,
+                `  contrib_start_work(issue_id=${params.issue_id})`,
+                ``,
+                `To continue on this branch anyway, confirm with the same call again.`,
+              ].join("\n"),
+            }],
+            isError: true,
+            details: { branch: currentBr, issueId, staleBranch: true },
+          };
+        }
+
+        (globalThis as any).__contrib_issueId = issueId;
+        (globalThis as any).__contrib_branchType = branchType;
+        const alreadyLinked = getLinkedIssueId(ctx.cwd) === issueId && currentBr.includes(`issue-${issueId}`);
+        const msg = alreadyLinked
+          ? [...issueInfo, "", `✅ Already on ${currentBr} (linked to #${issueId}). Resuming work.`].join("\n")
+          : [...issueInfo, "", `✅ Linked issue #${issueId} to existing branch ${currentBr}.`].join("\n");
+        return {
+          content: [{ type: "text", text: msg }],
+          details: { branch: currentBr, issueId, type: branchType, title: issueTitle },
+        };
+      }
+
+      // ═══ Case 2: Not on a feature branch → create one ═══
+      if (!isClean(ctx.cwd)) {
+        return { content: [{ type: "text", text: "⚠️ Working tree is not clean. Commit or stash changes before starting new work." }], isError: true, details: { clean: false } };
+      }
+
+      exec("git pull --ff-only gitea dev 2>/dev/null || git pull --ff-only origin dev 2>/dev/null || true", ctx.cwd);
+
+      const branchName = `${branchType}/issue-${issueId}`;
+      const r2 = exec(`git checkout -b ${shellEscape(branchName)}`, ctx.cwd);
+      if (!r2.ok) {
+        return { content: [{ type: "text", text: `Failed to create branch: ${r2.stderr}` }], isError: true, details: {} };
+      }
+
+      (globalThis as any).__contrib_issueId = issueId;
+      (globalThis as any).__contrib_branchType = branchType;
+
+      return {
+        content: [{
+          type: "text",
+          text: [
+            ...issueInfo,
+            "",
+            `✅ Work started on ${branchName}`,
+            `   Issue: #${issueId} — ${issueTitle}`,
+            `   Type: ${branchType}`,
+            ``,
+            `Next: make changes, then contrib_propose(message).`,
+          ].join("\n"),
+        }],
+        details: { branch: branchName, issueId, type: branchType, title: issueTitle },
+      };
+    }
+
+    // ── Validation disabled — original flow ──
+
+    if (isFeatureBranch) {
+      const remote = remoteBranchExists(ctx.cwd);
+      if (!remote.exists) {
+        const pr = await checkBranchPRState(ctx.cwd);
+        const prNote = pr
+          ? `\n\nPR ${pr.url} was ${pr.state === "merged" ? "already merged" : "closed"}.`
+          : "";
+        return {
+          content: [{
+            type: "text",
+            text: [
+              `⚠️  Branch "${currentBr}" has no remote — the PR was likely merged.`,
+              `${prNote}`,
+              ``,
+              `Continuing work on this branch risks creating orphaned commits.`,
+              ``,
+              `Recommended: start fresh work on a new branch:`,
+              `  git checkout main`,
+              `  contrib_start_work(issue_id=${params.issue_id})`,
+              ``,
+              `To continue on this branch anyway, confirm with the same call again.`,
+            ].join("\n"),
+          }],
+          isError: true,
+          details: { branch: currentBr, issueId, staleBranch: true },
+        };
+      }
+
+      (globalThis as any).__contrib_issueId = issueId;
+      (globalThis as any).__contrib_branchType = branchType;
+      const alreadyLinked = getLinkedIssueId(ctx.cwd) === issueId && currentBr.includes(`issue-${issueId}`);
+      const msg = alreadyLinked
+        ? `✅ Already on ${currentBr} (linked to #${issueId}). Resuming work.`
+        : `✅ Linked issue #${issueId} to existing branch ${currentBr}.`;
+      return {
+        content: [{ type: "text", text: msg }],
+        details: { branch: currentBr, issueId, type: branchType },
+      };
+    }
+
+    if (!isClean(ctx.cwd)) {
+      return { content: [{ type: "text", text: "⚠️ Working tree is not clean. Commit or stash changes before starting new work." }], isError: true, details: { clean: false } };
+    }
+
+    exec("git pull --ff-only gitea dev 2>/dev/null || git pull --ff-only origin dev 2>/dev/null || true", ctx.cwd);
+
+    const branchName = `${branchType}/issue-${issueId}`;
+    const r2 = exec(`git checkout -b ${shellEscape(branchName)}`, ctx.cwd);
+    if (!r2.ok) {
+      return { content: [{ type: "text", text: `Failed to create branch: ${r2.stderr}` }], isError: true, details: {} };
+    }
+
+    (globalThis as any).__contrib_issueId = issueId;
+    (globalThis as any).__contrib_branchType = branchType;
+
+    return {
+      content: [{ type: "text", text: [`✅ Work started on ${branchName}`, `   Issue: #${issueId}`, `   Type: ${branchType}`, ``, `Next: make changes, then contrib_propose(message).`].join("\n") }],
+      details: { branch: branchName, issueId, type: branchType },
+    };
+  },
+};

package/src/tools/status.ts

@@ -0,0 +1,67 @@
+import { Type } from "typebox";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { exec, currentBranch, isClean, hasUnpushed, getLinkedIssueId, remoteBranchExists, checkBranchPRState } from "../helpers";
+
+export const statusTool = {
+  name: "contrib_status" as const,
+  label: "Contribution Status",
+  description: "Show current branch, commit status, uncommitted changes, and PR status.",
+  parameters: Type.Object({}),
+  async execute(_toolCallId: string, _params: any, _signal: any, _onUpdate: any, ctx: ExtensionContext) {
+    const branch = currentBranch(ctx.cwd);
+    const clean = isClean(ctx.cwd);
+    const unpushed = hasUnpushed(ctx.cwd);
+    const issueId = getLinkedIssueId(ctx.cwd);
+    const lastHash = (globalThis as any).__contrib_lastHash || null;
+
+    const status = exec("git status --short", ctx.cwd);
+    const changes = status.ok && status.stdout ? status.stdout.split("\n").length : 0;
+
+    const lines = [
+      `📋 Contribution Status`,
+      `   Branch: ${branch || "(detached)"}`,
+      `   Issue: ${issueId ? `#${issueId}` : "(none)"}`,
+      `   Clean: ${clean ? "✅" : `❌ (${changes} changed files)`}`,
+      `   Unpushed: ${unpushed ? "⚠️ yes" : "✅ no"}`,
+      `   Last commit: ${lastHash || "(none)"}`,
+    ];
+
+    // ── Remote branch health ──
+    lines.push("");
+    const remote = remoteBranchExists(ctx.cwd);
+    if (branch && !remote.exists) {
+      lines.push(`   🌐 Remote branch: ❌ deleted (PR likely merged)`);
+      lines.push(`      ⚠️  Do NOT continue work on this branch.`);
+      lines.push(`      → Run contrib_start_work(issue_id) to start fresh work.`);
+    } else if (remote.exists) {
+      lines.push(`   🌐 Remote branch: ✅ on ${remote.remoteName}`);
+    }
+
+    // ── PR state ──
+    if (branch) {
+      const pr = await checkBranchPRState(ctx.cwd);
+      if (pr) {
+        const prIcon = pr.state === "merged" ? "🔀" : pr.state === "open" ? "🟢" : "🔴";
+        lines.push(`   📬 PR: ${prIcon} ${pr.state.toUpperCase()}`);
+        lines.push(`      ${pr.url}`);
+        if (pr.state === "merged") {
+          lines.push(`      ⚠️  This PR was already merged. Start fresh work.`);
+        }
+      } else {
+        lines.push(`   📬 PR: not found`);
+      }
+    }
+
+    if (!clean) {
+      lines.push("", "Changed files:");
+      for (const line of (status.stdout || "").split("\n").filter(Boolean).slice(0, 15)) {
+        lines.push(`   ${line}`);
+      }
+    }
+
+    return {
+      content: [{ type: "text", text: lines.join("\n") }],
+      details: { branch, clean, changes, unpushed, issueId },
+    };
+  },
+};

package/src/tools/submit.ts

@@ -0,0 +1,125 @@
+import { Type } from "typebox";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { exec, currentBranch, hasUnpushed, createPR, shellEscape, getLinkedIssueId, remoteBranchExists, checkBranchPRState } from "../helpers";
+
+export const submitTool = {
+  name: "contrib_submit" as const,
+  label: "Submit PR",
+  description: "Push the current branch and create a pull request.",
+  parameters: Type.Object({
+    title: Type.String({ description: "PR title" }),
+    body: Type.Optional(Type.String({ description: "PR description" })),
+    base: Type.Optional(Type.String({ description: "Target branch (default: dev)" })),
+    remote: Type.Optional(Type.String({ description: "Git remote name (auto-detects)" })),
+  }),
+  async execute(_toolCallId: string, params: any, _signal: any, _onUpdate: any, ctx: ExtensionContext) {
+    const branch = currentBranch(ctx.cwd);
+    const base = params.base || "dev";
+
+    const issueId = getLinkedIssueId(ctx.cwd);
+    if (!issueId) {
+      return {
+        content: [{
+          type: "text",
+          text: [
+            `❌ No Gitea issue linked.`,
+            ``,
+            `Before submitting a PR, link your work to an issue with:`,
+            `  contrib_start_work(issue_id)`,
+            ``,
+            `This ensures the PR closes the correct issue.`,
+          ].join("\n"),
+        }],
+        isError: true,
+        details: {},
+      };
+    }
+
+    if (!hasUnpushed(ctx.cwd) && !(globalThis as any).__contrib_lastHash) {
+      return { content: [{ type: "text", text: "No commits to push. Run contrib_propose() first." }], isError: true, details: {} };
+    }
+
+    // ── Pre-flight: Check if remote branch was deleted (PR likely merged) ──
+    const remote = remoteBranchExists(ctx.cwd);
+    if (!remote.exists) {
+      const pr = await checkBranchPRState(ctx.cwd);
+      if (pr?.state === "merged") {
+        return {
+          content: [{
+            type: "text",
+            text: [
+              `⛔ Cannot submit: PR for "${branch}" was already merged.`,
+              ``,
+              `   Merged PR: ${pr.url}`,
+              ``,
+              `The remote branch was deleted after merge. Continuing on this`,
+              `local branch creates orphaned work that is hard to track.`,
+              ``,
+              `Instead:`,
+              `   1. Switch to the base branch: git checkout main`,
+              `   2. Start fresh work: contrib_start_work(issue_id)`,
+            ].join("\n"),
+          }],
+          isError: true,
+          details: { branch, prState: pr.state, prUrl: pr.url },
+        };
+      }
+      // Remote deleted but PR state unknown — warn but allow
+      ctx.ui.notify(
+        "Remote branch deleted",
+        `Remote branch "${branch}" no longer exists. It may have been merged. Proceeding anyway...`,
+      );
+    }
+
+    // Check PR body for content that breaks CI shell scripts
+    const prBodyRaw = params.body || "";
+    if (prBodyRaw.includes("```")) {
+      return {
+        content: [{
+          type: "text",
+          text: [
+            "⚠️ PR body contains triple-backtick code blocks (```).",
+            "",
+            "These break the CI agent signature check step because the PR body",
+            "gets injected into a shell script. Use plain text instead:",
+            "",
+            "Instead of:",
+            "  ```bash",
+            "  docker compose up -d",
+            "  ```",
+            "",
+            "Use:",
+            "  docker compose up -d",
+            "",
+            "Remove all ``` markers and retry.",
+          ].join("\n"),
+        }],
+        isError: true,
+        details: {},
+      };
+    }
+
+    let remoteName = params.remote || "";
+    if (!remoteName) {
+      const remotes = exec("git remote", ctx.cwd);
+      const remoteList = remotes.ok ? remotes.stdout.split("\n").filter(Boolean) : [];
+      if (remoteList.includes("gitea")) remoteName = "gitea";
+      else if (remoteList.includes("origin")) remoteName = "origin";
+      else remoteName = remoteList[0] || "origin";
+    }
+
+    const push = exec(`git push -u ${shellEscape(remoteName)} ${shellEscape(branch)}`, ctx.cwd);
+    if (!push.ok) return { content: [{ type: "text", text: `Push failed: ${push.stderr}` }], isError: true, details: {} };
+
+    let prBody = params.body || "";
+    if (issueId) prBody += `\n\nCloses #${issueId}`;
+
+    const pr = await createPR(branch, base, params.title, prBody, ctx, remoteName);
+    if (!pr.ok) return { content: [{ type: "text", text: `Push succeeded but PR creation failed: ${pr.error}` }], isError: true, details: { branch } };
+
+    return {
+      content: [{ type: "text", text: [`🎉 PR created successfully!`, `   ${pr.url}`, `   Branch: ${branch} → ${base}`].join("\n") }],
+      details: { url: pr.url, branch, base },
+    };
+  },
+};

package/src/types.ts

@@ -0,0 +1,64 @@
+export interface BestPracticesConfig {
+  shortFrequentCommits: boolean;
+  maxLinesPerCommit: number;
+  requireAtomic: boolean;
+  maxUnrelatedDirs: number;
+  guidanceText: string[];
+}
+
+export interface ContribConfig {
+  branches: {
+    featPattern: string;
+    fixPattern: string;
+    chorePattern: string;
+  };
+  commits: {
+    convention: "conventional" | "simple";
+    maxSubjectLength: number;
+    scopes: string[];
+    bestPractices: BestPracticesConfig;
+  };
+  quality: {
+    lint: boolean;
+    typeCheck: boolean;
+    doctorAudit: boolean;
+    maxFilesChanged: number;
+    maxLinesAdded: number;
+  };
+  /** Validate that the linked Gitea issue actually exists before starting work (default: true) */
+  requireIssueValidation: boolean;
+}
+
+export const BEST_PRACTICES_DEFAULTS: BestPracticesConfig = {
+  shortFrequentCommits: true,
+  maxLinesPerCommit: 150,
+  requireAtomic: true,
+  maxUnrelatedDirs: 3,
+  guidanceText: [
+    "Commit after every logical unit of work.",
+    "Aim for < 150 lines per commit.",
+    "Each commit should do one thing — keep changes atomic.",
+  ],
+};
+
+export const DEFAULT_CONFIG: ContribConfig = {
+  branches: {
+    featPattern: "feat/",
+    fixPattern: "fix/",
+    chorePattern: "chore/",
+  },
+  commits: {
+    convention: "conventional",
+    maxSubjectLength: 72,
+    scopes: [],
+    bestPractices: { ...BEST_PRACTICES_DEFAULTS },
+  },
+  quality: {
+    lint: true,
+    typeCheck: true,
+    doctorAudit: true,
+    maxFilesChanged: 20,
+    maxLinesAdded: 500,
+  },
+  requireIssueValidation: true,
+};

package/src/validate.ts

@@ -0,0 +1,53 @@
+import * as path from "node:path";
+import type { ContribConfig } from "./types";
+import { exec, scanForConflictMarkers } from "./helpers";
+
+export function validateConventionalCommit(message: string, config: ContribConfig): { ok: true } | { ok: false; error: string } {
+  const firstLine = message.split("\n")[0].trim();
+  const convPattern = /^(feat|fix|chore|docs|style|refactor|test|perf|ci|build|revert)(\([^)]+\))?:\s.+$/;
+  if (!convPattern.test(firstLine)) {
+    return { ok: false, error: `Commit message must follow conventional commits format: type(scope): subject\nExamples: feat(api): add endpoint, fix: resolve null pointer, chore: update deps` };
+  }
+  if (firstLine.length > config.commits.maxSubjectLength) {
+    return { ok: false, error: `Subject line too long (${firstLine.length} > ${config.commits.maxSubjectLength} chars).` };
+  }
+  return { ok: true };
+}
+
+export function validateBranchName(branch: string): { ok: true } | { ok: false; error: string } {
+  if (/^(feat|fix|chore)\//.test(branch)) return { ok: true };
+  return { ok: false, error: `Branch name "${branch}" does not follow convention: feat/*, fix/*, or chore/*` };
+}
+
+export function runQualityGate(cwd: string, config: ContribConfig): { ok: true } | { ok: false; errors: string[] } {
+  const errors: string[] = [];
+
+  // ── Conflict marker check (MUST come first — safety-critical) ──
+  const conflictFiles = scanForConflictMarkers(cwd);
+  if (conflictFiles.length > 0) {
+    errors.push(
+      `Unresolved merge conflict markers found in staged files: ${conflictFiles.join(", ")}.\n  Remove all <<<<<<<, =======, >>>>>>> markers before committing.`,
+    );
+  }
+
+  const diff = exec("git diff --cached --name-only", cwd);
+  if (diff.ok) {
+    const files = diff.stdout.split("\n").filter(Boolean);
+    if (files.length > config.quality.maxFilesChanged) {
+      errors.push(`Too many files changed (${files.length} > ${config.quality.maxFilesChanged}).`);
+    }
+    const loc = exec("git diff --cached --numstat | awk '{s+=$1} END {print s}'", cwd);
+    if (loc.ok && parseInt(loc.stdout) > config.quality.maxLinesAdded) {
+      errors.push(`Too many lines added (${loc.stdout} > ${config.quality.maxLinesAdded}).`);
+    }
+  }
+  if (config.quality.typeCheck) {
+    const tsc = exec("npx tsc --noEmit 2>&1 || true", path.join(cwd, "factory"));
+    if (tsc.stdout.includes("error TS")) errors.push("TypeScript errors found. Run: npx tsc --noEmit");
+  }
+  if (config.quality.lint) {
+    const lint = exec("npm run lint 2>&1 || true", path.join(cwd, "factory"));
+    if (lint.stdout.includes("error") && !lint.stdout.includes("0 errors")) errors.push("Lint errors found.");
+  }
+  return errors.length === 0 ? { ok: true } : { ok: false, errors };
+}