@guilz-dev/sdlc-gh 0.1.0

package/scripts/check-issue-spec.mjs

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+/**
+ * Validate linked Issue CC-SD contract for L1 task:docs / task:test-fix PRs.
+ * Canonical field names live in scripts/lib/ccsd-contract.mjs.
+ */
+import { execSync } from "node:child_process";
+import {
+  CCSD_REQUIRED_FIELDS,
+  extractClosingIssueNumbers,
+  pickLinkedIssue,
+  resolveFetchFailureAction,
+  shouldEnforceCcsd,
+  validateCcsdFields,
+  validateLabelShape,
+} from "./lib/ccsd-contract.mjs";
+
+function ghJson(cmd) {
+  const out = execSync(cmd, {
+    encoding: "utf8",
+    env: process.env,
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+  return JSON.parse(out);
+}
+
+function warn(msg) {
+  console.warn(`::warning::${msg}`);
+}
+
+function error(msg) {
+  console.error(`::error::${msg}`);
+}
+
+function parseLabelEnv(name) {
+  return (process.env[name] || "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function enforcedByPrLabels() {
+  return shouldEnforceCcsd(parseLabelEnv("PR_LABELS"));
+}
+
+function proxyLabelsForFetchFailure(issueLabels = []) {
+  const prLabels = parseLabelEnv("PR_LABELS");
+  return [...new Set([...issueLabels, ...prLabels])];
+}
+
+function resolveIssueFromEnv() {
+  const issueBody = process.env.ISSUE_BODY;
+  const issueLabels = parseLabelEnv("ISSUE_LABELS");
+
+  if (issueBody !== undefined) {
+    return { body: issueBody, labels: issueLabels };
+  }
+  return null;
+}
+
+function fetchIssues(repo, issueNumbers) {
+  const fetched = [];
+  const failures = [];
+
+  for (const issueNumber of issueNumbers) {
+    try {
+      const issue = ghJson(
+        `gh issue view ${issueNumber} --repo ${repo} --json body,labels,number`,
+      );
+      fetched.push({
+        body: issue.body,
+        labels: (issue.labels || []).map((label) => label.name),
+        issueNumber: issue.number,
+      });
+    } catch (e) {
+      failures.push({ issueNumber, message: e.message });
+    }
+  }
+
+  return { fetched, failures };
+}
+
+function resolveIssueFromGitHub() {
+  const repo = process.env.GITHUB_REPOSITORY;
+  const prNumber = process.env.PR_NUMBER || process.env.GITHUB_EVENT_PR_NUMBER;
+  const prBody = process.env.PR_BODY;
+
+  if (!repo || !prNumber) return null;
+
+  let body = prBody ?? "";
+  let issueNumbers = [];
+
+  try {
+    const pr = ghJson(
+      `gh pr view ${prNumber} --repo ${repo} --json body,closingIssuesReferences`,
+    );
+    body = prBody ?? pr.body ?? "";
+    issueNumbers = (pr.closingIssuesReferences || []).map((issue) => issue.number);
+  } catch {
+    // Fall through to body keyword parsing.
+  }
+
+  if (issueNumbers.length === 0) {
+    issueNumbers = extractClosingIssueNumbers(body);
+  }
+
+  issueNumbers = [...new Set(issueNumbers)];
+
+  if (issueNumbers.length === 0) {
+    return { noIssue: true };
+  }
+
+  const { fetched, failures } = fetchIssues(repo, issueNumbers);
+
+  if (fetched.length === 0) {
+    const nums = failures.map((f) => f.issueNumber).join(", ");
+    return {
+      fetchFailed: true,
+      message: `Could not fetch linked issue(s) #${nums}`,
+      proxyLabels: proxyLabelsForFetchFailure(),
+    };
+  }
+
+  const picked = pickLinkedIssue(fetched);
+  if (picked.kind === "ambiguous") {
+    return {
+      ambiguous: true,
+      issueNumbers: picked.issueNumbers,
+    };
+  }
+
+  if (picked.kind === "issue") {
+    return {
+      body: picked.body,
+      labels: picked.labels,
+      issueNumber: picked.issueNumber,
+    };
+  }
+
+  return { noIssue: true };
+}
+
+function main() {
+  const issue =
+    resolveIssueFromEnv() ?? resolveIssueFromGitHub() ?? { noIssue: true };
+
+  if (issue.fetchFailed) {
+    const action = resolveFetchFailureAction(issue.proxyLabels);
+    if (action === "fail") {
+      error(
+        `${issue.message} — cannot verify CC-SD for L1 docs/test-fix delegation`,
+      );
+      process.exit(1);
+    }
+    warn(`${issue.message}; skipping CC-SD enforcement`);
+    process.exit(0);
+  }
+
+  if (issue.ambiguous) {
+    error(
+      `PR links multiple L1 docs/test-fix issues (#${issue.issueNumbers.join(", #")}); keep one enforced issue per PR`,
+    );
+    process.exit(1);
+  }
+
+  if (issue.noIssue) {
+    if (enforcedByPrLabels()) {
+      error(
+        "PR is labeled for L1 docs/test-fix but is not tied to a resolvable Issue; link exactly one Issue with a complete CC-SD contract",
+      );
+      process.exit(1);
+    }
+    warn(
+      "PR is not tied to a resolvable Issue; skipping CC-SD enforcement (CI uses Issue labels, not the form dropdown)",
+    );
+    process.exit(0);
+  }
+
+  const { body, labels, issueNumber } = issue;
+
+  const labelShape = validateLabelShape(labels);
+  if (!labelShape.ok) {
+    error(`Issue #${issueNumber}: ${labelShape.message}`);
+    process.exit(1);
+  }
+
+  if (!shouldEnforceCcsd(labels)) {
+    const taskLabels = labels.filter((l) => l.startsWith("task:")).join(", ") || "none";
+    const autonomy = labels.find((l) => l.startsWith("autonomy:")) || "none";
+    console.log(
+      `CC-SD check skipped (task=${taskLabels}, autonomy=${autonomy}) — v1 enforces only autonomy:L1 on task:docs / task:test-fix`,
+    );
+    process.exit(0);
+  }
+
+  const result = validateCcsdFields(body);
+  const prefix = issueNumber ? `Issue #${issueNumber}` : "Issue";
+
+  if (result.missing.length > 0) {
+    error(
+      `${prefix} missing required CC-SD fields: ${result.missing.join(", ")}. Required: ${CCSD_REQUIRED_FIELDS.join(", ")}`,
+    );
+    process.exit(1);
+  }
+
+  if (result.placeholder.length > 0) {
+    error(
+      `${prefix} has placeholder-only CC-SD fields: ${result.placeholder.join(", ")}. Replace template placeholders with real content.`,
+    );
+    process.exit(1);
+  }
+
+  console.log(`${prefix} CC-SD contract complete for L1 docs/test-fix delegation`);
+}
+
+main();

package/scripts/check-l1-readiness.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+import { appendFileSync } from "node:fs";
+import { formatReadinessSummary, runReadinessCheck } from "./lib/l1-readiness.mjs";
+
+function parseArgs(argv) {
+  const args = {
+    githubRepo: "",
+    template: false,
+    strict: false,
+    json: false,
+    summary: false,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const value = argv[i];
+    if (value === "--github-repo") {
+      args.githubRepo = argv[i + 1] ?? "";
+      i += 1;
+    } else if (value === "--template") {
+      args.template = true;
+    } else if (value === "--strict") {
+      args.strict = true;
+    } else if (value === "--json") {
+      args.json = true;
+    } else if (value === "--summary") {
+      args.summary = true;
+    } else if (value === "--help" || value === "-h") {
+      printHelp();
+      process.exit(0);
+    } else {
+      console.error(`Unknown argument: ${value}`);
+      printHelp();
+      process.exit(1);
+    }
+  }
+  return args;
+}
+
+function printHelp() {
+  console.log(`Usage: check-l1-readiness.mjs [options]
+
+Checks whether spec-driven L1 delegation can run on this repository.
+
+Options:
+  --github-repo owner/name   Explicit GitHub repository name
+  --template                 Template repository mode
+  --strict                   Exit non-zero on SKIP as well as FAIL (same as doctor)
+  --json                     Print machine-readable JSON summary
+  --summary                  Append markdown summary to GITHUB_STEP_SUMMARY when set
+`);
+}
+
+function printResult(entry) {
+  console.log(`${entry.status} ${entry.label}: ${entry.detail}`);
+  if (entry.fix) console.log(`  fix: ${entry.fix}`);
+}
+
+function printNextSteps(hasFail) {
+  console.log("\nNext");
+  if (hasFail) {
+    console.log("- Fix FAIL items above, then re-run `node scripts/check-l1-readiness.mjs --strict`.");
+  } else {
+    console.log("- Create a Task issue from `.github/ISSUE_TEMPLATE/task.yml`.");
+    console.log("- Fill CC-SD fields, then add labels: `task:docs` or `task:test-fix` + `autonomy:L1`.");
+    console.log("- Assign `triager`, then `implementer` to start autonomous Draft PR flow.");
+  }
+}
+
+const args = parseArgs(process.argv.slice(2));
+const report = runReadinessCheck(args);
+
+if (args.json) {
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+} else {
+  for (const entry of report.entries) printResult(entry);
+  printNextSteps(report.hasFail);
+}
+
+if (args.summary && process.env.GITHUB_STEP_SUMMARY) {
+  appendFileSync(process.env.GITHUB_STEP_SUMMARY, formatReadinessSummary(report));
+}
+
+process.exit(report.exitCode);

package/scripts/check-open-pr-limit.mjs

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * Safe-outputs substitute (Phase 0–2): warn when author has too many open PRs.
+ * See docs/operations.md — gh-aw safe_outputs replaces this in Phase 3+.
+ */
+import { execSync } from "node:child_process";
+
+const MAX_OPEN = Number(process.env.HARNESS_MAX_OPEN_PRS || 3);
+const author = process.env.PR_AUTHOR || process.env.GITHUB_ACTOR;
+
+if (!author) {
+  console.log("No PR author context; skipping open PR limit check");
+  process.exit(0);
+}
+
+let count = 0;
+try {
+  const out = execSync(
+    `gh pr list --author "${author}" --state open --json number --jq 'length'`,
+    { encoding: "utf8", env: process.env },
+  );
+  count = Number(out.trim()) || 0;
+} catch {
+  console.warn("::warning::Could not query open PRs (gh CLI unavailable); skipping");
+  process.exit(0);
+}
+
+console.log(`Open PRs by ${author}: ${count} (warn above ${MAX_OPEN})`);
+
+if (count > MAX_OPEN) {
+  console.warn(
+    `::warning::Author has ${count} open PRs (limit ${MAX_OPEN}). Close or merge before opening more.`,
+  );
+}

package/scripts/doctor.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { execFileSync, spawnSync } from "node:child_process";
+import { loadLabels } from "./lib/github-config.mjs";
+import { localChecks, resolveStackId, result } from "./lib/doctor-local.mjs";
+
+const argv = process.argv.slice(2);
+if (argv.includes("--help") || argv.includes("-h")) {
+  console.log(`Usage: doctor.mjs [--strict] [--template]
+
+  --strict    Fail on SKIP checks (default: fail only on FAIL)
+  --template  Allow multiple product-ci workflows (template repository mode)
+`);
+  process.exit(0);
+}
+
+const strict = argv.includes("--strict");
+const templateMode = argv.includes("--template");
+
+function resolveRepoRoot() {
+  try {
+    return execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+  } catch {
+    return process.cwd();
+  }
+}
+
+function printResult(entry) {
+  console.log(`${entry.status} ${entry.label}: ${entry.detail}`);
+  if (entry.fix) console.log(`  fix: ${entry.fix}`);
+}
+
+function ghAvailable() {
+  return spawnSync("gh", ["--version"], { stdio: "ignore" }).status === 0;
+}
+
+function ghAuthed() {
+  return spawnSync("gh", ["auth", "status"], { stdio: "ignore" }).status === 0;
+}
+
+function ghJson(args, cwd) {
+  const result = spawnSync("gh", args, {
+    cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (result.status !== 0) {
+    throw new Error(result.stderr.trim() || "gh command failed");
+  }
+  return JSON.parse(result.stdout);
+}
+
+function ghJsonPages(args, cwd) {
+  const result = spawnSync("gh", [...args, "--paginate", "--slurp"], {
+    cwd,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  if (result.status !== 0) {
+    throw new Error(result.stderr.trim() || "gh command failed");
+  }
+  return JSON.parse(result.stdout);
+}
+
+function githubChecks(repoRoot, stackId) {
+  const entries = [];
+  if (!ghAvailable()) {
+    entries.push(result("SKIP", "GitHub CLI", "gh is not installed", "Install `gh` to verify labels and rulesets."));
+    return entries;
+  }
+  if (!ghAuthed()) {
+    entries.push(result("SKIP", "GitHub auth", "gh is not authenticated", "Run `gh auth login` to verify GitHub state."));
+    return entries;
+  }
+
+  if (!stackId) {
+    entries.push(
+      result(
+        "SKIP",
+        "required status checks",
+        "stack could not be resolved",
+        "Ensure exactly one product-ci-*.yml workflow exists or run setup-wizard.",
+      ),
+    );
+    return entries;
+  }
+
+  let repo;
+  try {
+    repo = ghJson(["repo", "view", "--json", "nameWithOwner"], repoRoot).nameWithOwner;
+  } catch (error) {
+    entries.push(result("SKIP", "GitHub repo", error.message, "Run doctor from a cloned GitHub repository."));
+    return entries;
+  }
+
+  let remoteLabels = [];
+  try {
+    remoteLabels = ghJsonPages(["api", `repos/${repo}/labels`], repoRoot).flat();
+  } catch (error) {
+    entries.push(result("SKIP", "GitHub labels", error.message, "Run `./scripts/setup-github.sh` or apply `.github/labels.yml` manually."));
+    return entries;
+  }
+  const expectedLabels = loadLabels(join(repoRoot, ".github/labels.yml")).map((label) => label.name);
+  const remoteLabelNames = new Set(remoteLabels.map((label) => label.name));
+  const missingLabels = expectedLabels.filter((name) => !remoteLabelNames.has(name));
+  if (missingLabels.length === 0) {
+    entries.push(result("PASS", "GitHub labels", "all required labels exist"));
+  } else {
+    entries.push(
+      result(
+        "FAIL",
+        "GitHub labels",
+        `missing labels: ${missingLabels.join(", ")}`,
+        "Run `./scripts/setup-github.sh` to sync labels.",
+      ),
+    );
+  }
+
+  let rulesets = [];
+  try {
+    rulesets = ghJson(["api", `repos/${repo}/rulesets`], repoRoot);
+  } catch (error) {
+    entries.push(result("SKIP", "GitHub rulesets", error.message, "Grant repo admin permission or import `.github/ruleset.example.json` manually."));
+    return entries;
+  }
+
+  const ruleset = rulesets.find((entry) => entry.name === "main-protection");
+  if (!ruleset) {
+    entries.push(result("FAIL", "main-protection ruleset", "missing", "Run `./scripts/setup-github.sh` to create it."));
+    return entries;
+  }
+  entries.push(result("PASS", "main-protection ruleset", "exists"));
+
+  try {
+    const details = ghJson(["api", `repos/${repo}/rulesets/${ruleset.id}`], repoRoot);
+    if (details.enforcement === "active") {
+      entries.push(result("PASS", "ruleset enforcement", "active"));
+    } else {
+      entries.push(result("FAIL", "ruleset enforcement", `expected active, got ${details.enforcement}`, "Update the ruleset enforcement to active."));
+    }
+
+    const requiredRule = (details.rules ?? []).find((rule) => rule.type === "required_status_checks");
+    const contexts = new Set((requiredRule?.parameters?.required_status_checks ?? []).map((check) => check.context));
+    const expectedContexts = ["harness-static", "diff-size", "issue-spec-check", `product-ci-${stackId}`];
+    const missingContexts = expectedContexts.filter((context) => !contexts.has(context));
+    if (missingContexts.length === 0) {
+      entries.push(result("PASS", "required status checks", `includes ${expectedContexts.join(", ")}`));
+    } else {
+      entries.push(
+        result(
+          "FAIL",
+          "required status checks",
+          `missing contexts: ${missingContexts.join(", ")}`,
+          "Run `./scripts/setup-github.sh` to update the ruleset.",
+        ),
+      );
+    }
+  } catch (error) {
+    entries.push(result("SKIP", "ruleset details", error.message, "Inspect the ruleset in GitHub Settings -> Rules."));
+  }
+
+  return entries;
+}
+
+const repoRoot = resolveRepoRoot();
+const local = localChecks(repoRoot, { templateMode });
+const stackId = local.stackId || resolveStackId(repoRoot);
+const entries = [...local.entries, ...githubChecks(repoRoot, stackId)];
+for (const entry of entries) printResult(entry);
+
+const hasFail = entries.some((entry) => entry.status === "FAIL");
+const hasSkip = entries.some((entry) => entry.status === "SKIP");
+process.exit(hasFail || (strict && hasSkip) ? 1 : 0);

package/scripts/emit-gh-aw-dogfood-report.mjs

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+/**
+ * Emit machine-readable gh-aw dogfood evaluation report.
+ */
+import { execSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  buildDogfoodReport,
+  evaluateDogfoodScope,
+  evaluateSafeOutputsForWorkflows,
+  GH_AW_SOURCE_WORKFLOWS,
+  parseDogfoodLabels,
+  parseGhAwLockMetadata,
+} from "./lib/gh-aw-dogfood.mjs";
+
+export const DOGFOOD_REPORT_DIR = "dogfood-report";
+
+function hasGhAw() {
+  try {
+    execSync("gh aw version", { stdio: ["pipe", "pipe", "pipe"] });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function changedFiles() {
+  const base = process.env.BASE_SHA;
+  if (!base) return [];
+  try {
+    return execSync(`git diff --name-only ${base}...HEAD`, { encoding: "utf8" })
+      .split("\n")
+      .filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function evaluateScope() {
+  const files = changedFiles();
+  const labels = parseDogfoodLabels(process.env.PR_LABELS);
+  const { ok, issues } = evaluateDogfoodScope(files, labels);
+  return { ok, issues };
+}
+
+/** Lock metadata header presence (compile step catches byte-level drift). */
+function evaluateLockMetadata() {
+  const issues = [];
+  for (const wf of GH_AW_SOURCE_WORKFLOWS) {
+    if (!existsSync(wf.lock)) {
+      issues.push(`${wf.lock} missing`);
+      continue;
+    }
+    const metadata = parseGhAwLockMetadata(readFileSync(wf.lock, "utf8"));
+    if (!metadata) issues.push(`${wf.lock} missing gh-aw-metadata header`);
+    if (!existsSync(wf.md)) issues.push(`${wf.md} missing for ${wf.id}`);
+  }
+  return { ok: issues.length === 0, issues };
+}
+
+function evaluateCompile() {
+  if (!hasGhAw()) {
+    return {
+      ok: true,
+      skipped: true,
+      issues: ["gh aw CLI not available"],
+    };
+  }
+
+  const issues = [];
+  for (const wf of GH_AW_SOURCE_WORKFLOWS) {
+    if (!existsSync(wf.md) || !existsSync(wf.lock)) continue;
+    const before = readFileSync(wf.lock, "utf8");
+    try {
+      execSync(`gh aw compile ${wf.id}.md`, { stdio: ["pipe", "pipe", "pipe"] });
+    } catch (error) {
+      issues.push(`${wf.id}: ${error.stderr?.toString().trim() || error.message}`);
+      continue;
+    }
+    const after = readFileSync(wf.lock, "utf8");
+    if (before !== after) issues.push(`${wf.lock} would change after compile`);
+  }
+
+  return { ok: issues.length === 0, skipped: false, issues };
+}
+
+function main() {
+  const safeOutputs = evaluateSafeOutputsForWorkflows((path) => readFileSync(path, "utf8"));
+  const report = buildDogfoodReport({
+    repo: process.env.GITHUB_REPOSITORY || "unknown/unknown",
+    scope: evaluateScope(),
+    safeOutputs,
+    compile: evaluateCompile(),
+    lockDrift: evaluateLockMetadata(),
+  });
+
+  const outDir = process.env.DOGFOOD_REPORT_DIR || DOGFOOD_REPORT_DIR;
+  mkdirSync(outDir, { recursive: true });
+  const jsonPath = join(outDir, "gh-aw-dogfood-report.json");
+  writeFileSync(jsonPath, `${JSON.stringify(report, null, 2)}\n`, "utf8");
+
+  console.log(`Wrote ${jsonPath}`);
+  console.log(`::notice::gh_aw_dogfood_pass=${report.pass}`);
+
+  if (!report.pass) {
+    console.error("::error::gh-aw dogfood evaluation failed");
+    process.exit(1);
+  }
+}
+
+main();