dev-loops 0.1.0

package/scripts/docs/validate-no-duplicate-rules.mjs

@@ -0,0 +1,250 @@
+#!/usr/bin/env node
+/**
+ * validate-no-duplicate-rules.mjs — CI guardrail: detect duplicated imperative
+ * rule text across skill doc files under skills/.
+ *
+ * Scans skills/ for Markdown files, extracts imperative sentences (those
+ * containing "must", "never", "do not", or "require"/"required"), and reports
+ * any sentence that appears in more than one file.
+ *
+ * Symlink note:
+ *   .pi/skills/ -> ../skills on this repo, so scanning skills/ covers both.
+ *
+ * False-positive suppression:
+ *   - Fenced code blocks (``` or ~~~)
+ *   - Inline code spans (`)
+ *   - Blockquotes (lines starting with ">")
+ *   - Markdown link URLs (text inside (...))
+ *   - Headings (lines starting with "#")
+ *   - Only cross-file duplicates reported (same-file dupes are intentional)
+ *
+ * Exclusion list:
+ *   Duplicates where all occurrences are within canonical contract docs
+ *   (which own their content by design) are suppressed. Duplicates involving
+ *   any non-canonical file are still reported.
+ *   Known intentional duplicates (mirrored skill procedure text) are also
+ *   excluded so that the guardrail enforces new duplication without failing
+ *   on deliberate mirrors.
+ *
+ * Exit 0 when clean, exit 1 when duplicates found.
+ */
+
+import { readFile, readdir } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { isDirectCliRun } from "../_core-helpers.mjs";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, "..", "..");
+const SKILLS_DIR = path.join(REPO_ROOT, "skills");
+
+const CANONICAL_CONTRACT_DOCS = new Set([
+  "skills/docs/copilot-loop-operations.md",
+  "skills/docs/public-dev-loop-contract.md",
+]);
+
+/**
+ * Known intentional duplicates: text that appears in multiple skill files
+ * because it is deliberately mirrored (shared procedure sections, template
+ * mirrors, etc.). These are excluded from cross-file duplicate reporting so
+ * the guardrail stays fatal for new duplicates without noise from mirrors.
+ */
+const KNOWN_INTENTIONAL_DUPLICATES = new Set([
+  "- **PERSISTENCE RULE: Do not exit your session until the PR is merged or you hit a hard stop that requires conductor authorization.**",
+  "If any required bundled contract doc is missing from the installed skill layout, treat that as a packaging/installer bug.",
+  "Each reviewer starts in fresh context with the briefing artifact, inspects the diff, returns findings via output artifacts only, and never edits files.",
+  "3. **Consolidation:** reconcile all review outputs into a consolidated fix plan with classified findings (must-fix, worth-fixing-now, defer).",
+  "5. **Fix cycle:** apply only accepted must-fix changes on the same branch.",
+  "- remains a stop/fix state, never a wait loop",
+  "Do not create a fresh PR directly in ready-for-review state unless the user explicitly overrides that policy for the current PR scope.",
+  "Each reviewer starts in fresh context (subagent({context:\"fresh\"}) mandatory), inspects the diff, returns findings via output artifacts only, and never edits files. **Before starting:** run to self-verify fresh context; refuse to proceed on contamination.",
+  "If includes , then worth-fixing-now findings must be fixed before the gate can reach .",
+]);
+
+const IMPERATIVE_PATTERNS = [
+  /\bmust\b/i,
+  /\bnever\b/i,
+  /\bdo not\b/i,
+  /\brequire[sd]?\b/i,
+];
+
+const MIN_SENTENCE_LENGTH = 20;
+
+const USAGE = `Usage: validate-no-duplicate-rules.mjs [--help]
+
+Scan skills/ for duplicated imperative rule text across Markdown files.
+Exit 0 when no duplicates found. Exit 1 when duplicates found.
+
+Options:
+  --help, -h   Show this help`.trim();
+
+
+export async function* collectMarkdownFiles(dir, repoRoot = REPO_ROOT) {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch (err) {
+    // Ignore ENOENT (missing directory) silently; other errors must fail loudly
+    // so the CI guardrail doesn't silently pass with 0 files scanned.
+    if (err?.code === "ENOENT") {
+      return;
+    }
+    throw err;
+  }
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+
+    if (entry.isSymbolicLink()) {
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      yield* collectMarkdownFiles(fullPath, repoRoot);
+    } else if (entry.isFile() && entry.name.endsWith(".md")) {
+      yield fullPath;
+    }
+  }
+}
+
+export function isImperativeSentence(sentence) {
+  return IMPERATIVE_PATTERNS.some((pattern) => pattern.test(sentence));
+}
+
+export function normalizeSentence(text) {
+  return text.replace(/\s+/g, " ").trim();
+}
+
+/**
+ * Normalize a repo-relative path to POSIX separators.
+ * On Windows, path.relative() produces backslashes, which would break
+ * comparisons against CANONICAL_CONTRACT_DOCS and report formatting.
+ */
+function toPosixPath(p) {
+  return p.replace(/\\/g, "/");
+}
+
+export function extractSentences(content) {
+  const lines = content.split(/\r?\n/);
+  const sentences = [];
+  let inFencedBlock = false;
+  let fencedDelimiter = "";
+
+  for (let i = 0; i < lines.length; i++) {
+    let line = lines[i];
+
+    const rawTrimmed = line.trim();
+
+    if (/^\s*#/.test(line)) {
+      continue;
+    }
+
+    if (/^\s*>/.test(line)) {
+      continue;
+    }
+
+    const fenceMatch = rawTrimmed.match(/^(```|~~~)/);
+    if (fenceMatch) {
+      if (!inFencedBlock) {
+        inFencedBlock = true;
+        fencedDelimiter = fenceMatch[1];
+        continue;
+      } else if (rawTrimmed.startsWith(fencedDelimiter)) {
+        inFencedBlock = false;
+        fencedDelimiter = "";
+        continue;
+      }
+    }
+
+    if (inFencedBlock) {
+      continue;
+    }
+
+    line = line
+      .replace(/`[^`]*`/g, "")
+      .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1");
+
+    const parts = line.split(/(?<=[.!?])\s+(?=[A-Z])/);
+    for (const part of parts) {
+      const normalized = normalizeSentence(part);
+      if (normalized.length >= MIN_SENTENCE_LENGTH && isImperativeSentence(normalized)) {
+        sentences.push({ text: normalized, line: i + 1 });
+      }
+    }
+  }
+
+  return sentences;
+}
+
+export async function scanSkills(skillsDir = SKILLS_DIR, repoRoot = REPO_ROOT) {
+  const fileMap = new Map();
+  let totalFilesScanned = 0;
+
+  for await (const filePath of collectMarkdownFiles(skillsDir, repoRoot)) {
+    const relativePath = toPosixPath(path.relative(repoRoot, filePath));
+
+    totalFilesScanned++;
+    const content = await readFile(filePath, "utf8");
+    const sentences = extractSentences(content);
+
+    for (const { text, line } of sentences) {
+      if (!fileMap.has(text)) {
+        fileMap.set(text, []);
+      }
+      fileMap.get(text).push({ file: relativePath, line });
+    }
+  }
+
+  const duplicates = new Map();
+  for (const [text, occurrences] of fileMap) {
+    if (KNOWN_INTENTIONAL_DUPLICATES.has(text)) {
+      continue;
+    }
+    const uniqueFiles = new Set(occurrences.map((o) => o.file));
+    if (uniqueFiles.size > 1) {
+      // Suppress duplicates where all occurrences are within canonical
+      // contract docs (these own their content by design and may mirror
+      // each other).  Duplicates that involve any non-canonical file
+      // are still reported.
+      const allCanonical = [...uniqueFiles].every((f) => CANONICAL_CONTRACT_DOCS.has(f));
+      if (!allCanonical) {
+        duplicates.set(text, occurrences);
+      }
+    }
+  }
+
+  return { fileMap, duplicates, totalFilesScanned };
+}
+
+async function main(argv = process.argv.slice(2)) {
+  if (argv.includes("--help") || argv.includes("-h")) {
+    process.stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+
+  const { fileMap, duplicates, totalFilesScanned } = await scanSkills();
+
+  if (duplicates.size === 0) {
+    process.stdout.write(`No duplicate imperative rules found across skill docs.\n`);
+    process.stdout.write(`\n${totalFilesScanned} files scanned, ${fileMap.size} unique imperative sentences extracted, 0 duplicates found.\n`);
+    return 0;
+  }
+
+  process.stdout.write(`Duplicate imperative rules found across skill docs:\n\n`);
+  for (const [text, occurrences] of duplicates) {
+    for (const { file, line } of occurrences) {
+      process.stdout.write(`  ${file}:${line}\n`);
+    }
+    process.stdout.write(`    "${text}"\n\n`);
+  }
+
+  process.stdout.write(`${totalFilesScanned} files scanned, ${fileMap.size} unique imperative sentences extracted, ${duplicates.size} duplicates found.\n`);
+  return 1;
+}
+
+// Only run main() when executed directly, not when imported for testing.
+if (isDirectCliRun(import.meta.url)) {
+  const exitCode = await main();
+  process.exitCode = exitCode;
+}

package/scripts/github/_review-thread-mutations.mjs

@@ -0,0 +1,214 @@
+import { spawn } from "node:child_process";
+import { isCopilotLogin, parseReviewThreads } from "../_core-helpers.mjs";
+import { fetchGithubReviewThreadsPayload } from "./capture-review-threads.mjs";
+export const MIN_DISMISSAL_REASON_LENGTH = 30;
+export function hasCommitShaReference(text) {
+  const trimmed = text.trim();
+  const hexTokens = trimmed.match(/\b[0-9a-f]{7,40}\b/gi) ?? [];
+  const hasHexLetterToken = hexTokens.some((token) => /[a-f]/i.test(token));
+  const hasContextualNumericRef =
+    /\b(?:fixed\s+in|commit|sha|rev(?:ision)?)\s+[0-9a-f]{7,40}\b/i.test(trimmed)
+    || /\/commit\/[0-9a-f]{7,40}\b/i.test(trimmed);
+  return hasHexLetterToken || hasContextualNumericRef;
+}
+export function validateResolutionMessage(body) {
+  const trimmedBody = body.trim();
+  const hasCommitSha = hasCommitShaReference(trimmedBody);
+  const hasDismissalReason = trimmedBody.length >= MIN_DISMISSAL_REASON_LENGTH;
+  if (!hasCommitSha && !hasDismissalReason) {
+    throw new Error(
+      `Reply body (${trimmedBody.length} characters after trimming) must contain either a commit SHA reference or a dismissal reason (at least ${MIN_DISMISSAL_REASON_LENGTH} characters after trimming). `
+      + 'Bare acknowledgments like "Acknowledged." are not valid resolutions.',
+    );
+  }
+  return {
+    trimmedBody,
+    hasCommitSha,
+    hasDismissalReason,
+  };
+}
+function runChildWithInput(command, args, env, stdinText) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      env,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += String(chunk);
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+    if (stdinText === undefined) {
+      child.stdin.end();
+    } else {
+      child.stdin.end(stdinText);
+    }
+    child.on("error", reject);
+    child.on("close", (code) => {
+      resolve({ code, stdout, stderr });
+    });
+  });
+}
+function parseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`Invalid JSON from gh: ${text.trim() || "<empty>"}`);
+  }
+}
+export function parseReplyPayload(payload) {
+  const replyId = payload?.id;
+  const replyUrl = payload?.html_url;
+  if (!Number.isFinite(replyId) || typeof replyUrl !== "string" || replyUrl.trim().length === 0) {
+    throw new Error("Reply payload from gh did not include both id and html_url");
+  }
+  return {
+    replyId,
+    replyUrl,
+  };
+}
+const RESOLVE_REVIEW_THREAD_MUTATION = [
+  "mutation($threadId: ID!) {",
+  "  resolveReviewThread(input: { threadId: $threadId }) {",
+  "    thread {",
+  "      id",
+  "      isResolved",
+  "    }",
+  "  }",
+  "}",
+].join("\n");
+export async function captureParsedReviewThreads(
+  { repo, pr },
+  { env = process.env, ghCommand = "gh" } = {},
+) {
+  const payload = await fetchGithubReviewThreadsPayload({ repo, pr }, { env, ghCommand });
+  return parseReviewThreads(payload);
+}
+export function assertReplyTargetFromSnapshot(parsed, { repo, pr, commentId, threadId }) {
+  const targetCommentId = String(commentId);
+  const thread = parsed.threads.find((entry) => entry.id === threadId) ?? null;
+  const comment = parsed.comments.find((entry) => entry.databaseId === targetCommentId) ?? null;
+  if (thread === null) {
+    throw new Error(`Review thread ${threadId} was not found on pull request ${repo}#${pr}`);
+  }
+  if (comment === null) {
+    throw new Error(`Review comment ${commentId} was not found on pull request ${repo}#${pr}`);
+  }
+  if (comment.threadId !== threadId) {
+    throw new Error(`Review comment ${commentId} does not belong to review thread ${threadId} on pull request ${repo}#${pr}`);
+  }
+  return {
+    thread,
+    comment,
+  };
+}
+export async function validateReplyTarget(
+  { repo, pr, commentId, threadId },
+  { env = process.env, ghCommand = "gh" } = {},
+) {
+  const parsed = await captureParsedReviewThreads({ repo, pr }, { env, ghCommand });
+  return {
+    parsed,
+    ...assertReplyTargetFromSnapshot(parsed, { repo, pr, commentId, threadId }),
+  };
+}
+export async function postReply(
+  { repo, pr, commentId, body },
+  { env = process.env, ghCommand = "gh" } = {},
+) {
+  const result = await runChildWithInput(
+    ghCommand,
+    [
+      "api",
+      "-X",
+      "POST",
+      `repos/${repo}/pulls/${pr}/comments/${commentId}/replies`,
+      "--input",
+      "-",
+    ],
+    env,
+    `${JSON.stringify({ body })}\n`,
+  );
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`gh command failed: ${detail}`);
+  }
+  return parseJson(result.stdout);
+}
+export async function resolveThread(threadId, { env = process.env, ghCommand = "gh" } = {}) {
+  const result = await runChildWithInput(
+    ghCommand,
+    [
+      "api",
+      "graphql",
+      "--field",
+      `threadId=${threadId}`,
+      "--field",
+      `query=${RESOLVE_REVIEW_THREAD_MUTATION}`,
+    ],
+    env,
+  );
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`gh command failed: ${detail}`);
+  }
+  const payload = parseJson(result.stdout);
+  return payload?.data?.resolveReviewThread?.thread;
+}
+export async function replyAndMaybeResolve(
+  {
+    repo,
+    pr,
+    commentId,
+    threadId,
+    body,
+    resolve = true,
+    validatedSnapshot = null,
+  },
+  { env = process.env, ghCommand = "gh" } = {},
+) {
+  if (validatedSnapshot) {
+    assertReplyTargetFromSnapshot(validatedSnapshot, { repo, pr, commentId, threadId });
+  } else {
+    await validateReplyTarget({ repo, pr, commentId, threadId }, { env, ghCommand });
+  }
+  const reply = parseReplyPayload(await postReply(
+    {
+      repo,
+      pr,
+      commentId,
+      body,
+    },
+    { env, ghCommand },
+  ));
+  if (!resolve) {
+    return {
+      replyId: reply.replyId,
+      replyUrl: reply.replyUrl,
+      resolved: false,
+    };
+  }
+  const resolvedThread = await resolveThread(threadId, { env, ghCommand });
+  if (!resolvedThread?.isResolved) {
+    throw new Error(`Review thread did not resolve successfully: ${threadId}`);
+  }
+  return {
+    replyId: reply.replyId,
+    replyUrl: reply.replyUrl,
+    resolved: true,
+  };
+}
+export function authorMatchesFilter(commentAuthorLogin, authorFilter) {
+  const normalizedLogin = typeof commentAuthorLogin === "string" ? commentAuthorLogin.trim() : "";
+  const normalizedFilter = typeof authorFilter === "string" ? authorFilter.trim() : "";
+  if (normalizedLogin.length === 0 || normalizedFilter.length === 0) {
+    return false;
+  }
+  if (normalizedFilter.toLowerCase() === "copilot") {
+    return isCopilotLogin(normalizedLogin) || normalizedLogin.toLowerCase() === "copilot";
+  }
+  return normalizedLogin.toLowerCase() === normalizedFilter.toLowerCase();
+}

package/scripts/github/capture-review-threads.mjs

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  formatCliError,
+  isDirectCliRun,
+  parseJsonText,
+  parseReviewThreads,
+  readInput,
+} from "../_core-helpers.mjs";
+import { parsePrNumber, requireOptionValue, runChild } from "../_cli-primitives.mjs";
+import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+export const REVIEW_THREADS_QUERY = [
+  "query($owner: String!, $name: String!, $pr: Int!) {",
+  "  repository(owner: $owner, name: $name) {",
+  "    pullRequest(number: $pr) {",
+  "      reviewThreads(first: 100) {",
+  "        nodes {",
+  "          id",
+  "          isResolved",
+  "          comments(first: 100) {",
+  "            nodes {",
+  "              id",
+  "              databaseId",
+  "              body",
+  "              author {",
+  "                login",
+  "                __typename",
+  "              }",
+  "            }",
+  "          }",
+  "        }",
+  "      }",
+  "    }",
+  "  }",
+  "}",
+].join("\n");
+const HELP = `Usage: capture-review-threads.mjs [--input <path> | --repo <owner/name> --pr <number>] [--output <path>]
+Capture review threads from a GitHub PR or from a local JSON snapshot.
+Modes:
+  --input <path>                Read JSON snapshot from file
+  (no mode flag)                Read JSON snapshot from stdin
+  --repo <owner/name> --pr <n>  Fetch live review threads from GitHub PR
+Options:
+  --output <path>   Write JSON output to file in addition to stdout
+  --help, -h        Show this help
+Exit codes:
+  0   Success
+  1   Error
+`;
+export function parseCaptureCliArgs(argv) {
+  const args = [...argv];
+  const options = {
+    inputPath: undefined,
+    outputPath: undefined,
+    repo: undefined,
+    pr: undefined,
+    help: false,
+  };
+  while (args.length > 0) {
+    const token = args.shift();
+    if (token === "--help" || token === "-h") {
+      options.help = true;
+      return options;
+    }
+    if (token === "--input") {
+      options.inputPath = requireOptionValue(args, "--input");
+      continue;
+    }
+    if (token === "--output") {
+      options.outputPath = requireOptionValue(args, "--output");
+      continue;
+    }
+    if (token === "--repo") {
+      options.repo = requireOptionValue(args, "--repo");
+      continue;
+    }
+    if (token === "--pr") {
+      options.pr = parsePrNumber(requireOptionValue(args, "--pr"));
+      continue;
+    }
+    throw new Error(`Unknown argument: ${token}`);
+  }
+  const hasLiveArgs = options.repo !== undefined || options.pr !== undefined;
+  const hasCompleteLiveArgs = options.repo !== undefined && options.pr !== undefined;
+  if (hasLiveArgs && !hasCompleteLiveArgs) {
+    throw new Error("Live GitHub capture requires both --repo <owner/name> and --pr <number>");
+  }
+  if (options.inputPath && hasCompleteLiveArgs) {
+    throw new Error("Choose exactly one input source: --input <path>, stdin, or live --repo/--pr");
+  }
+  return options;
+}
+export async function fetchGithubReviewThreadsPayload(
+  { repo, pr },
+  { env = process.env, ghCommand = "gh" } = {},
+) {
+  const { owner, name } = parseRepoSlug(repo);
+  const result = await runChild(
+    ghCommand,
+    [
+      "api",
+      "graphql",
+      "--field",
+      `owner=${owner}`,
+      "--field",
+      `name=${name}`,
+      "--field",
+      `pr=${pr}`,
+      "--field",
+      `query=${REVIEW_THREADS_QUERY}`,
+    ],
+    env,
+  );
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`gh command failed: ${detail}`);
+  }
+  return parseJsonText(result.stdout);
+}
+function createSuccessPayload(source, result, outputPath) {
+  return {
+    ok: true,
+    source,
+    ...(outputPath ? { outputPath } : {}),
+    ...result,
+  };
+}
+async function writeOutputFile(outputPath, payload) {
+  await mkdir(path.dirname(outputPath), { recursive: true });
+  await writeFile(outputPath, `${JSON.stringify(payload)}\n`, "utf8");
+}
+export async function runCli(
+  argv = process.argv.slice(2),
+  {
+    stdin = process.stdin,
+    stdout = process.stdout,
+    env = process.env,
+    ghCommand = "gh",
+  } = {},
+) {
+  const options = parseCaptureCliArgs(argv);
+  if (options.help) {
+    stdout.write(HELP);
+    return;
+  }
+  let source;
+  let parsed;
+  if (options.repo && options.pr !== undefined) {
+    source = {
+      type: "github",
+      repo: options.repo,
+      pr: options.pr,
+    };
+    parsed = parseReviewThreads(await fetchGithubReviewThreadsPayload(
+      { repo: options.repo, pr: options.pr },
+      { env, ghCommand },
+    ));
+  } else if (options.inputPath) {
+    source = {
+      type: "input",
+      inputPath: options.inputPath,
+    };
+    parsed = parseReviewThreads(parseJsonText(await readInput({ inputPath: options.inputPath, stdin })));
+  } else {
+    source = { type: "stdin" };
+    parsed = parseReviewThreads(parseJsonText(await readInput({ stdin })));
+  }
+  const payload = createSuccessPayload(source, parsed, options.outputPath);
+  if (options.outputPath) {
+    await writeOutputFile(options.outputPath, payload);
+  }
+  stdout.write(`${JSON.stringify(payload)}\n`);
+}
+if (isDirectCliRun(import.meta.url)) {
+  runCli().catch((error) => {
+    process.stderr.write(`${formatCliError(error)}\n`);
+    process.exitCode = 1;
+  });
+}