@guilz-dev/sdlc-gh 0.1.0

package/scripts/lib/ccsd-contract.mjs

@@ -0,0 +1,212 @@
+/**
+ * Canonical CC-SD contract — single source of truth for field names.
+ * Used by CI validation, regression tests, and template alignment checks.
+ */
+
+/** @type {readonly string[]} */
+export const CCSD_REQUIRED_FIELDS = [
+  "Goal",
+  "Non-goals",
+  "Constraints",
+  "Acceptance criteria",
+  "Rollback hints",
+];
+
+/** @type {readonly string[]} */
+export const CCSD_OPTIONAL_FIELDS = ["Additional context"];
+
+/** @type {readonly string[]} */
+export const CCSD_ALL_FIELDS = [...CCSD_REQUIRED_FIELDS, ...CCSD_OPTIONAL_FIELDS];
+
+/** L1 task classes that require a complete CC-SD contract in v1. */
+export const CCSD_ENFORCED_TASK_CLASSES = ["docs", "test-fix"];
+
+/** PR template summary fields that mirror the Issue contract. */
+export const CCSD_PR_SUMMARY_FIELDS = [
+  "Goal implemented",
+  "Non-goals preserved",
+  "Constraints handled",
+  "Acceptance criteria",
+  "Rollback",
+];
+
+/**
+ * Placeholder text from the Issue template — treated as missing content.
+ * @type {readonly string[]}
+ */
+export const CCSD_PLACEHOLDER_SNIPPETS = [
+  "One short paragraph describing what this task achieves.",
+  "- Item the task must not do or change",
+  "- Technical or policy limits (stack, paths, time)",
+  "- [ ] Criterion 1",
+  "- [ ] Criterion 2",
+  "How to revert this change immediately if needed.",
+];
+
+/**
+ * Parse GitHub Issue form body sections (### Label headers).
+ * @param {string} body
+ * @returns {Record<string, string>}
+ */
+export function parseIssueSections(body) {
+  const sections = {};
+  if (!body?.trim()) return sections;
+
+  const parts = body.split(/^### /m);
+  for (const part of parts.slice(1)) {
+    const newline = part.indexOf("\n");
+    if (newline === -1) continue;
+    const title = part.slice(0, newline).trim();
+    const content = part.slice(newline + 1).trim();
+    sections[title] = content;
+  }
+  return sections;
+}
+
+function normalizeLine(line) {
+  return line.replace(/\s+/g, " ").trim();
+}
+
+function isPlaceholderLine(line) {
+  const normalized = normalizeLine(line);
+  if (!normalized) return true;
+  return CCSD_PLACEHOLDER_SNIPPETS.some((snippet) => normalized === snippet);
+}
+
+/**
+ * @param {string} content
+ * @returns {boolean}
+ */
+export function isPlaceholderContent(content) {
+  if (!content?.trim()) return true;
+
+  const stripped = content.replace(/<!--[\s\S]*?-->/g, "").trim();
+  if (!stripped) return true;
+
+  const lines = stripped
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line && !/^\-\s*\[\s*\]\s*$/.test(line));
+
+  if (lines.length === 0) return true;
+
+  // Single paragraph (Goal, Rollback hints): exact match only — extra text is valid.
+  if (lines.length === 1 && !lines[0].startsWith("-")) {
+    return isPlaceholderLine(lines[0]);
+  }
+
+  // Bullet lists: placeholder-only when every remaining line is a template snippet.
+  return lines.every((line) => isPlaceholderLine(line));
+}
+
+/**
+ * Validate CC-SD fields in an Issue body.
+ * @param {string} issueBody
+ * @returns {{ ok: boolean, missing: string[], placeholder: string[] }}
+ */
+export function validateCcsdFields(issueBody) {
+  const sections = parseIssueSections(issueBody);
+  const missing = [];
+  const placeholder = [];
+
+  for (const field of CCSD_REQUIRED_FIELDS) {
+    const content = sections[field];
+    if (!content?.trim()) {
+      missing.push(field);
+    } else if (isPlaceholderContent(content)) {
+      placeholder.push(field);
+    }
+  }
+
+  return {
+    ok: missing.length === 0 && placeholder.length === 0,
+    missing,
+    placeholder,
+  };
+}
+
+/**
+ * Whether CC-SD enforcement applies for the given labels.
+ * @param {string[]} labels
+ * @returns {boolean}
+ */
+export function shouldEnforceCcsd(labels) {
+  const normalized = labels.map((l) => l.trim());
+  const taskLabels = normalized
+    .filter((l) => l.startsWith("task:"))
+    .map((l) => l.replace(/^task:/, ""));
+  if (taskLabels.length !== 1) return false;
+
+  const isL1 = normalized.some((l) => l === "autonomy:L1");
+  return isL1 && CCSD_ENFORCED_TASK_CLASSES.includes(taskLabels[0]);
+}
+
+/**
+ * @param {string[]} labels
+ * @returns {{ ok: true } | { ok: false, message: string }}
+ */
+export function validateLabelShape(labels) {
+  const normalized = labels.map((l) => l.trim());
+  const taskLabels = normalized.filter((l) => l.startsWith("task:"));
+  const autonomyLabels = normalized.filter((l) => l.startsWith("autonomy:"));
+
+  if (taskLabels.length > 1) {
+    return {
+      ok: false,
+      message: `Issue has multiple task:* labels (${taskLabels.join(", ")}); keep exactly one`,
+    };
+  }
+  if (autonomyLabels.length > 1) {
+    return {
+      ok: false,
+      message: `Issue has multiple autonomy:* labels (${autonomyLabels.join(", ")}); keep exactly one`,
+    };
+  }
+  return { ok: true };
+}
+
+/**
+ * When linked Issues cannot be fetched, fail only if proxy labels indicate L1 docs/test-fix.
+ * @param {string[]} proxyLabels - Issue labels, or PR labels as fallback
+ * @returns {"fail" | "warn_skip"}
+ */
+export function resolveFetchFailureAction(proxyLabels) {
+  return shouldEnforceCcsd(proxyLabels) ? "fail" : "warn_skip";
+}
+
+/**
+ * Extract issue numbers from PR closing keywords (fixes #N, closes #N, …).
+ * Bare #N mentions are ignored to avoid matching unrelated references.
+ * @param {string} body
+ * @returns {number[]}
+ */
+export function extractClosingIssueNumbers(body) {
+  if (!body) return [];
+  const numbers = new Set();
+  const pattern = /(?:close[sd]?|fix(?:e[sd])?|resolve[sd]?)\s+#(\d+)/gi;
+  for (const match of body.matchAll(pattern)) {
+    numbers.add(Number(match[1]));
+  }
+  return [...numbers];
+}
+
+/**
+ * Pick the Issue to validate when a PR links multiple Issues.
+ * Prefers the single L1 docs/test-fix candidate; flags ambiguity when several match.
+ * @param {{ body: string, labels: string[], issueNumber: number }[]} issues
+ * @returns {{ kind: "none" } | { kind: "ambiguous", issueNumbers: number[] } | { kind: "issue", body: string, labels: string[], issueNumber: number }}
+ */
+export function pickLinkedIssue(issues) {
+  if (!issues?.length) return { kind: "none" };
+
+  const enforced = issues.filter((issue) => shouldEnforceCcsd(issue.labels));
+  if (enforced.length > 1) {
+    return {
+      kind: "ambiguous",
+      issueNumbers: enforced.map((issue) => issue.issueNumber),
+    };
+  }
+  if (enforced.length === 1) return { kind: "issue", ...enforced[0] };
+
+  return { kind: "issue", ...issues[0] };
+}

package/scripts/lib/diff-size.mjs

@@ -0,0 +1,103 @@
+/** Pure helpers for diff-size / autonomy gate (testable without git). */
+
+export const LIMITS = {
+  L1: { loc: 300, files: 8 },
+  L2: { loc: 120, files: 4 },
+  L3: { loc: 60, files: 2 },
+};
+
+export const SENSITIVE_PATH_PREFIXES = [".github/workflows/", "infra/"];
+
+export function parseLabelInput(input) {
+  return String(input || "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+export function resolveAutonomyLevel(labels) {
+  if (labels.some((l) => l.includes("autonomy:L3"))) return "L3";
+  if (labels.some((l) => l.includes("autonomy:L2"))) return "L2";
+  if (labels.some((l) => l.includes("autonomy:L0"))) return "L0";
+  return "L1";
+}
+
+export function resolveLimits(level) {
+  if (level === "L0") return null;
+  return LIMITS[level] ?? LIMITS.L1;
+}
+
+export function resolveEnforcementMode(level, { l1HardFail = false } = {}) {
+  if (level === "L0") return "proposal-only";
+  if (level === "L2" || level === "L3") return "hard-fail";
+  if (level === "L1" && l1HardFail) return "hard-fail";
+  return "warn";
+}
+
+export function aggregateDiffStats(numstatText) {
+  let add = 0;
+  let del = 0;
+  let files = 0;
+
+  for (const line of String(numstatText).split("\n").filter(Boolean)) {
+    const [a, d] = line.split("\t");
+    if (a === "-" && d === "-") continue;
+    add += Number(a) || 0;
+    del += Number(d) || 0;
+    files += 1;
+  }
+
+  return { add, del, loc: add + del, files };
+}
+
+export function isOverLimit(stats, limits) {
+  if (!limits) return false;
+  return stats.loc > limits.loc || stats.files > limits.files;
+}
+
+export function formatSummary(level, stats, limits) {
+  if (!limits) {
+    return `Autonomy: ${level} | LOC: ${stats.loc} | Files: ${stats.files} (proposal only)`;
+  }
+  return `Autonomy: ${level} | LOC: ${stats.loc}/${limits.loc} | Files: ${stats.files}/${limits.files}`;
+}
+
+export function formatOverLimitMessage(level) {
+  return `Change size exceeds ${level} limits`;
+}
+
+export function findSensitivePathWarnings(diffFiles, labels) {
+  const hasInfra = labels.some((l) => l.includes("task:infra"));
+  const warnings = [];
+  for (const file of diffFiles) {
+    if (SENSITIVE_PATH_PREFIXES.some((prefix) => file.startsWith(prefix)) && !hasInfra) {
+      warnings.push(`${file} changed without task:infra label`);
+    }
+  }
+  return warnings;
+}
+
+export function evaluateDiffSize({
+  labels,
+  numstatText,
+  diffFiles = [],
+  l1HardFail = false,
+}) {
+  const level = resolveAutonomyLevel(labels);
+  const limits = resolveLimits(level);
+  const mode = resolveEnforcementMode(level, { l1HardFail });
+  const stats = aggregateDiffStats(numstatText);
+  const overLimit = isOverLimit(stats, limits);
+  const sensitiveWarnings = findSensitivePathWarnings(diffFiles, labels);
+
+  return {
+    level,
+    limits,
+    mode,
+    stats,
+    overLimit,
+    sensitiveWarnings,
+    summary: formatSummary(level, stats, limits),
+    overLimitMessage: overLimit ? formatOverLimitMessage(level) : null,
+  };
+}

package/scripts/lib/doctor-local.mjs

@@ -0,0 +1,179 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getStack } from "./stacks.mjs";
+import { CODEOWNERS_PLACEHOLDER } from "./setup-wizard.mjs";
+
+export function result(status, label, detail, fix = "") {
+  return { status, label, detail, fix };
+}
+
+/** @param {string} repoRoot */
+export function listProductCiWorkflows(repoRoot) {
+  const workflowsDir = join(repoRoot, ".github/workflows");
+  if (!existsSync(workflowsDir)) return [];
+  return readdirSync(workflowsDir).filter((name) => /^product-ci-([^.]+)\.yml$/.test(name));
+}
+
+/** @param {string} repoRoot */
+export function inferStackFromProductCi(repoRoot) {
+  const workflows = listProductCiWorkflows(repoRoot);
+  if (workflows.length !== 1) return "";
+  const match = workflows[0].match(/^product-ci-([^.]+)\.yml$/);
+  return match?.[1] ?? "";
+}
+
+/** @param {string} repoRoot */
+export function resolveStackId(repoRoot) {
+  const stackFile = join(repoRoot, ".harness-stack");
+  if (existsSync(stackFile)) {
+    const stackId = readFileSync(stackFile, "utf8").trim();
+    try {
+      getStack(stackId);
+      return stackId;
+    } catch {
+      return "";
+    }
+  }
+
+  const inferred = inferStackFromProductCi(repoRoot);
+  if (!inferred) return "";
+  try {
+    getStack(inferred);
+    return inferred;
+  } catch {
+    return "";
+  }
+}
+
+export function localChecks(repoRoot, { nodeVersion = process.versions.node, templateMode = false } = {}) {
+  const entries = [];
+  let stackId = "";
+  const stackFile = join(repoRoot, ".harness-stack");
+
+  if (!existsSync(stackFile)) {
+    const inferred = inferStackFromProductCi(repoRoot);
+    if (inferred) {
+      try {
+        getStack(inferred);
+        stackId = inferred;
+        entries.push(
+          result(
+            "PASS",
+            ".harness-stack",
+            `inferred ${inferred} from product-ci-${inferred}.yml (local file is gitignored; optional: run setup-wizard to write it)`,
+          ),
+        );
+      } catch {
+        entries.push(
+          result(
+            "FAIL",
+            ".harness-stack",
+            `missing and product-ci-${inferred}.yml maps to unknown stack`,
+            "Run `./scripts/setup-wizard.mjs` or `./scripts/bootstrap-harness.sh`.",
+          ),
+        );
+      }
+    } else {
+      entries.push(
+        result(
+          "FAIL",
+          ".harness-stack",
+          "missing",
+          "Run `./scripts/setup-wizard.mjs` or `./scripts/bootstrap-harness.sh`.",
+        ),
+      );
+    }
+  } else {
+    stackId = readFileSync(stackFile, "utf8").trim();
+    try {
+      getStack(stackId);
+      entries.push(result("PASS", ".harness-stack", `stack is ${stackId}`));
+    } catch {
+      entries.push(
+        result(
+          "FAIL",
+          ".harness-stack",
+          `unknown stack value: ${stackId}`,
+          "Set .harness-stack to a supported stack id.",
+        ),
+      );
+    }
+  }
+
+  const workflowsDir = join(repoRoot, ".github/workflows");
+  const productWorkflows = existsSync(workflowsDir)
+    ? readdirSync(workflowsDir).filter((name) => /^product-ci-.*\.yml$/.test(name))
+    : [];
+  if (productWorkflows.length === 1) {
+    entries.push(result("PASS", "product-ci workflow", `found ${productWorkflows[0]}`));
+  } else if (templateMode && productWorkflows.length > 1) {
+    entries.push(
+      result(
+        "PASS",
+        "product-ci workflow",
+        `template repo: ${productWorkflows.length} workflows (${productWorkflows.join(", ")})`,
+      ),
+    );
+  } else {
+    entries.push(
+      result(
+        "FAIL",
+        "product-ci workflow",
+        `expected exactly 1 product-ci workflow, found ${productWorkflows.length}`,
+        "Re-run `./scripts/bootstrap-harness.sh` or `./scripts/setup-wizard.mjs --template`.",
+      ),
+    );
+  }
+
+  const codeownersFile = join(repoRoot, ".github/CODEOWNERS");
+  if (!existsSync(codeownersFile)) {
+    entries.push(result("FAIL", "CODEOWNERS", "missing", "Re-run `./scripts/bootstrap-harness.sh`."));
+  } else {
+    const hasPlaceholder = readFileSync(codeownersFile, "utf8").includes(CODEOWNERS_PLACEHOLDER);
+    if (templateMode) {
+      if (hasPlaceholder) {
+        entries.push(result("PASS", "CODEOWNERS", "template placeholder preserved"));
+      } else {
+        entries.push(
+          result(
+            "FAIL",
+            "CODEOWNERS",
+            "template repo must keep placeholder owners",
+            `Restore ${CODEOWNERS_PLACEHOLDER} in .github/CODEOWNERS (do not commit personal or org-specific owners here).`,
+          ),
+        );
+      }
+    } else if (hasPlaceholder) {
+      entries.push(
+        result(
+          "FAIL",
+          "CODEOWNERS",
+          "placeholder team still present",
+          "Run `./scripts/setup-wizard.mjs` or `./scripts/bootstrap-harness.sh --codeowners-team @org/team`.",
+        ),
+      );
+    } else {
+      entries.push(result("PASS", "CODEOWNERS", "team placeholder replaced"));
+    }
+  }
+
+  const nodeMajor = Number.parseInt(nodeVersion.split(".")[0], 10);
+  if (nodeMajor >= 22) {
+    entries.push(result("PASS", "Node.js", `version ${nodeVersion}`));
+  } else {
+    entries.push(
+      result(
+        "FAIL",
+        "Node.js",
+        `version ${nodeVersion} is below 22`,
+        "Install Node.js 22+ for local parity with CI.",
+      ),
+    );
+  }
+
+  if (!stackId) {
+    stackId = resolveStackId(repoRoot);
+  }
+
+  return { entries, stackId };
+}

package/scripts/lib/e2e-manifest.mjs

@@ -0,0 +1,76 @@
+/** Pure validation for e2e-bench manifest (testable without filesystem). */
+
+export const SUPPORTED_CLASSES = [
+  "docs",
+  "test-fix",
+  "refactor",
+  "feature-small",
+  "dependency-bump",
+  "infra",
+  "security-sensitive",
+];
+
+const QUARTER_MS = 90 * 24 * 60 * 60 * 1000;
+
+export function validateLastRotated(lastRotated) {
+  if (!lastRotated) {
+    return { valid: false, message: "manifest missing last_rotated" };
+  }
+  const parsed = new Date(lastRotated);
+  if (Number.isNaN(parsed.getTime())) {
+    return { valid: false, message: `invalid last_rotated: ${lastRotated}` };
+  }
+  const stale = Date.now() - parsed.getTime() > QUARTER_MS;
+  return { valid: true, stale, parsed };
+}
+
+export function validateManifest(manifest, taskFileIds = []) {
+  const errors = [];
+  const warnings = [];
+  const tasks = manifest.tasks || [];
+  const minTasks = manifest.min_tasks ?? 5;
+  const fileIdSet = new Set(taskFileIds);
+
+  if (tasks.length < minTasks) {
+    errors.push(`Need at least ${minTasks} e2e tasks (found ${tasks.length})`);
+  }
+
+  const rotation = validateLastRotated(manifest.last_rotated);
+  if (!rotation.valid) {
+    errors.push(rotation.message);
+  } else if (rotation.stale) {
+    warnings.push("E2E bench not rotated in 90 days — review manifest");
+  }
+
+  const seenIds = new Set();
+  const manifestIds = new Set();
+
+  for (const entry of tasks) {
+    const id = entry?.id;
+    if (!id) {
+      errors.push("Manifest task missing id");
+      continue;
+    }
+    if (seenIds.has(id)) {
+      errors.push(`Duplicate manifest task id: ${id}`);
+    }
+    seenIds.add(id);
+    manifestIds.add(id);
+
+    if (!fileIdSet.has(id)) {
+      errors.push(`Missing task file: evals/e2e-bench/tasks/${id}.yml`);
+    }
+
+    if (entry.class && !SUPPORTED_CLASSES.includes(entry.class)) {
+      errors.push(`Unsupported task class for ${id}: ${entry.class}`);
+    }
+  }
+
+  for (const fileId of taskFileIds) {
+    if (!manifestIds.has(fileId)) {
+      errors.push(`Orphan task file not listed in manifest: ${fileId}.yml`);
+    }
+  }
+
+  return { errors, warnings, taskCount: tasks.length, minTasks };
+}