arkgate 2.11.0 → 2.12.0

package/bin/lib/ci-and-commands.mjs

@@ -0,0 +1,386 @@
+/**
+ * Package-manager commands, agent instruction text, and CI workflow templates.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  arkCommand,
+  detectPackageManager,
+  execCommandParts,
+  execRunner,
+  DEFAULT_INTENT_PREFIXES,
+  DEFAULT_LAYER_DIRECTORIES,
+} from '../ark-shared.mjs';
+import { falseGreenAdoptionGap } from './field-install.mjs';
+import { PREFERRED_MCP_BIN } from './hook-templates.mjs';
+import { readPackageJson } from './gate-files.mjs';
+
+// Field-install helpers re-exported for callers that import from this module.
+export {
+  ensureBaselineFlagInCheckCommand,
+  syncBaselineIntoCheckSurfaces,
+  pinArkgateDevDependency,
+  IO_DIR_SEGMENTS,
+  detectContractFalseGreenRisk,
+  FALSE_GREEN_GAP_ID,
+  falseGreenAdoptionGap,
+} from './field-install.mjs';
+
+export function checkArgsForRoot(root, { requireGates = false } = {}) {
+  const baselineFlag = fs.existsSync(path.join(root, '.ark-baseline.json'))
+    ? ' --baseline .ark-baseline.json'
+    : '';
+  const profile = requireGates ? '--strict' : '--strict-config';
+  return `--root . --config ark.config.json ${profile}${baselineFlag}`;
+}
+
+
+export function packageManager(root) {
+  // CI always require-gates; baseline follows checkArgsForRoot.
+  const checkArgs = checkArgsForRoot(root, { requireGates: true });
+  // Same detection as every emitted command (execRunner): honors the packageManager field and
+  // won't let a stray pnpm-lock.yaml hijack an npm project (package-lock.json wins the tie).
+  const pm = detectPackageManager(root);
+  if (pm === 'pnpm') {
+    return {
+      cache: 'pnpm',
+      setup: ['corepack enable'],
+      install: 'pnpm install --frozen-lockfile',
+      // Same runner as execRunner(): skip pnpm's verify-deps gate (ERR_PNPM_IGNORED_BUILDS).
+      run: `pnpm --config.verify-deps-before-run=false exec ark-check ${checkArgs}`,
+    };
+  }
+  if (pm === 'yarn') {
+    return {
+      cache: 'yarn',
+      setup: ['corepack enable'],
+      install: 'yarn install --frozen-lockfile',
+      run: `yarn ark-check ${checkArgs}`,
+    };
+  }
+  // Monorepo hosts (e.g. Next app under frontend/) often have a root package.json only for
+  // arkgate while real app deps live in frontend/package.json. Install both so CI can resolve
+  // the tree; ark-check itself only needs the root arkgate install.
+  const frontendPkg = fs.existsSync(path.join(root, 'frontend', 'package.json'));
+  const rootInstall = fs.existsSync(path.join(root, 'package-lock.json')) ? 'npm ci' : 'npm install';
+  const install = frontendPkg
+    ? `${rootInstall} && (cd frontend && ${fs.existsSync(path.join(root, 'frontend', 'package-lock.json')) ? 'npm ci' : 'npm install'})`
+    : rootInstall;
+  return {
+    cache: 'npm',
+    setup: [],
+    install,
+    run: `npx ark-check ${checkArgs}`,
+  };
+}
+
+// The runner prefix (npx / pnpm exec / yarn) is added per project by arkCheckCommand
+// so a pnpm-only repo never gets an `npx` instruction — see execRunner() in ark-shared.mjs.
+export function arkCheckCommand(root) {
+  return arkCommand(root, 'ark-check', checkArgsForRoot(root));
+}
+
+export function checkArchitectureScriptSnippet(root) {
+  // The package manager's runner resolves the installed binary; `node bin/ark-check.mjs`
+  // only works inside Ark's own repo. Package-manager aware so a pnpm/yarn repo isn't
+  // handed an `npx` alias that violates its "never npx" policy.
+  return `"check:architecture": "${arkCheckCommand(root)}"`;
+}
+
+// Canonical agent contract. AGENTS.md and the Cursor rule both derive from this single
+// source so the steps can never drift out of sync between the two files. `steps(checkCommand)`
+// is a builder because the check command's runner prefix varies with the package manager.
+const AGENT_CONTRACT = {
+  manifestResource: 'ark://manifest',
+  steps: (checkCommand) => [
+    `Read the Ark contract from \`ark://manifest\` when the MCP server is available.`,
+    `Keep source files inside the layer boundaries declared in \`ark.config.json\`.`,
+    `Do not bypass Ark publishers, event contracts, or source metadata for runtime mutations.`,
+    `After edits, run \`${checkCommand}\`.`,
+    `If Ark reports violations, fix the architecture instead of weakening the gate.`,
+  ],
+  // Cursor-only guidance: the write-time validate_code tool is available in
+  // Cursor's runtime but has no equivalent in a plain AGENTS.md read.
+  cursorValidateStep: `Validate the full post-edit file content with the \`validate_code\` tool before writing whenever your runtime supports it.`,
+};
+
+export function layerPlacementTable() {
+  const rows = DEFAULT_INTENT_PREFIXES.map((entry) => {
+    const dirs = (DEFAULT_LAYER_DIRECTORIES[entry.layer] ?? [])
+      .map((directory) => `\`${directory}/\``)
+      .join(', ');
+    return `| ${entry.layer} | ${dirs} | ${entry.prefixes.map((p) => `\`${p}\``).join(', ')} |`;
+  }).join('\n');
+  return `| Layer | Conventional directories (under the source root) | Intent prefixes |
+|-------|---------------------------------------------------|-----------------|
+${rows}`;
+}
+
+export function agentInstructions(root) {
+  const checkCmd = arkCheckCommand(root);
+  const startCmd = arkCommand(root, 'ark', 'start');
+  const doctorCmd = arkCommand(root, 'ark-check', '--doctor');
+  const steps = AGENT_CONTRACT.steps(checkCmd)
+    .map((step, index) => `${index + 1}. ${step}`)
+    .join('\n');
+  return `# Ark Enforcement
+
+## Default agent flow (if unsure, do only this)
+
+1. If \`ark.config.json\` is missing: run \`${startCmd}\` once.
+2. For adoption / cleanup / “make architecture sound”: run the **\`/ark-autopilot\`** skill
+   (explore first → dual plan: remediation + pattern bets → safe fixes → gates). Day-zero
+   origin is frozen by \`ark start\`/\`ark init\` (or autopilot if missing) **before** agent docs.
+   Do **not** invent a second architecture curriculum outside the routing table below — when a
+   trigger matches, use that skill; when unsure, stay on autopilot.
+3. Status anytime: \`${doctorCmd}\` (status light + next action — not a mode picker).
+4. After ordinary feature edits: run \`${checkCmd}\`. On violations → **\`/ark-fix\`** (or
+   \`/ark-place\` for new files, \`/ark-contract\` only if the contract itself is wrong).
+
+Skills are **dual-engine**: deterministic CLI sensors + exploratory read of *this* repo — not JSON-only wrappers.
+When a skill says **STOP — do not continue this skill as complete**, stop and invoke the named handoff skill.
+
+### Subagent fan-out
+If the host supports **parallel subagents**, skills may ask you to fan out **read-only**
+scouts (disjoint path scopes) and merge in the parent. If the host does **not**,
+**fall back to sequential** — one cluster/step at a time. Never parallel-write the same
+files; never weaken the gate via subagents.
+
+## Skill routing (triggers → skill)
+
+| When | Invoke |
+|------|--------|
+| Unsure / make architecture sound | **/ark-autopilot** (default) |
+| Need map / opportunities only (no apply) | \`/ark-explore\` |
+| Greenfield shape / empty tree | \`/ark-architect\` |
+| Brownfield / wrong contract / false-green | \`/ark-adopt\` then \`/ark-contract\` if globs wrong |
+| Edit \`ark.config.json\` layers/rules/intents | \`/ark-contract\` |
+| New file “where does this go?” | \`/ark-place\` |
+| Gate violation on a change | \`/ark-fix\` |
+| Drive plan to goal.met | \`/ark-loop\` |
+| Deep coverage + ranked audit | \`/ark-coverage\` |
+| Design trade-offs (no package LLM) | \`/ark-think\` |
+| Explain / HTML report tour | \`/ark-explain\` |
+| Bump arkgate + refresh hosts | \`/ark-upgrade\` |
+| Optional runtime kernel migrate | \`/ark-runtime\` |
+
+## Before editing TypeScript or JavaScript source files
+
+${steps}
+
+## Where new code belongs
+
+\`ark.config.json\` is authoritative for this project. When creating a NEW kind of code
+that no existing layer covers (a saga, a background job, a read model, ...), use the
+default 11-layer placement below and add the layer to \`ark.config.json\` — do not invent
+an ungoverned location:
+
+${layerPlacementTable()}
+
+The project is only considered Ark-enforced when the write gate and CI gate pass
+(runtime path only if this project opted into the kernel).
+`;
+}
+
+export function mcpJson(root) {
+  return `${JSON.stringify({
+    mcpServers: {
+      ark: {
+        type: 'stdio',
+        // Prefer arkgate-mcp; ark-mcp alias still works for one major.
+        ...execCommandParts(root, PREFERRED_MCP_BIN, ['--root', '.', '--config', 'ark.config.json']),
+      },
+    },
+  }, null, 2)}\n`;
+}
+
+// Sample for docs/ — `ark-check --install-agent-gates --tools codex` auto-merges the real
+// block (with absolute paths) into ~/.codex/config.toml. This copy is a reference only, so
+// it flags the two gotchas of hand-editing the global config: absolute paths (config.toml is
+// loaded without the project as cwd) and the required restart.
+export function codexTomlSnippet(root) {
+  const { command, args } = execCommandParts(root, PREFERRED_MCP_BIN, [
+    '--root',
+    '/absolute/path/to/project',
+    '--config',
+    '/absolute/path/to/project/ark.config.json',
+  ]);
+  const argsToml = args.map((value) => `"${value}"`).join(', ');
+  return `# Add to ~/.codex/config.toml (or $CODEX_HOME/config.toml), then RESTART Codex —
+# it does not hot-load MCP servers. Use ABSOLUTE paths: config.toml is global, so
+# "." would resolve against Codex's launch dir, not this project. Prefer:
+#   ark-check --install-agent-gates --tools codex   (auto-merges the absolute paths)
+[mcp_servers.ark]
+command = "${command}"
+args = [${argsToml}]
+`;
+}
+
+/**
+ * Compact always-on rule for instruction-tier hosts (Windsurf, Cline, GitHub Copilot,
+ * Kiro, ...): agents that read a project rule file but have no MCP tools or hooks.
+ * Derived from the same AGENT_CONTRACT as AGENTS.md and the Cursor rule so the steps
+ * can never drift; points at AGENTS.md for the full placement table.
+ */
+export function instructionRule(root) {
+  const steps = AGENT_CONTRACT.steps(arkCheckCommand(root))
+    .map((step, index) => `${index + 1}. ${step}`)
+    .join('\n');
+  return `# Ark architecture contract
+
+This project's architecture is governed by Ark (\`ark.config.json\` is authoritative).
+Before writing or editing TypeScript or JavaScript source files:
+
+${steps}
+
+See \`AGENTS.md\` for the full contract and the layer placement table.
+`;
+}
+
+export function cursorRule(root) {
+  return `---
+description: Ark architecture contract
+alwaysApply: true
+---
+
+Before writing or editing TypeScript or JavaScript source files, read the
+\`${AGENT_CONTRACT.manifestResource}\` resource from the \`ark\` MCP server when available.
+
+${AGENT_CONTRACT.cursorValidateStep} After edits, run:
+
+\`\`\`bash
+${arkCheckCommand(root)}
+\`\`\`
+
+If Ark reports violations, fix the architecture instead of bypassing the gate.
+`;
+}
+
+// Default CI Node when the project declares nothing. A current LTS, NOT the
+// oldest supported: the npm-ci-lockfile-mismatch failure only happens when CI's
+// npm is OLDER than the npm that wrote the lockfile, so defaulting high is safer.
+// Bumped 20 → 22 → 24 as consumer lockfiles moved with newer local npm.
+const DEFAULT_CI_NODE_VERSION = '24';
+
+/**
+ * Read Node majors from sibling GitHub Actions workflows (not ark-check.yml).
+ * A stale generated ark gate must not pin us to an old default when the project's
+ * real CI already runs a newer Node (classic "CI green / Ark red" false gate).
+ * @param {string} root
+ * @returns {string | null} highest major found, or null
+ */
+export function detectNodeMajorFromWorkflows(root) {
+  const dir = path.join(root, '.github', 'workflows');
+  if (!fs.existsSync(dir)) return null;
+  let entries;
+  try {
+    entries = fs.readdirSync(dir);
+  } catch {
+    return null;
+  }
+  const majors = [];
+  for (const name of entries) {
+    if (!/\.ya?ml$/i.test(name)) continue;
+    // Ignore our own template so regenerating does not re-read a stale 20/22 pin.
+    if (/^ark-check\.ya?ml$/i.test(name)) continue;
+    let text;
+    try {
+      text = fs.readFileSync(path.join(dir, name), 'utf8');
+    } catch {
+      continue;
+    }
+    // node-version: '24' | "24" | 24 | 24.x  (skip node-version-file: lines)
+    for (const match of text.matchAll(/(?:^|\n)\s*(?:- )?node-version:\s*['"]?(\d+)/g)) {
+      majors.push(Number(match[1]));
+    }
+  }
+  if (majors.length === 0) return null;
+  // Highest major: older CI npm is the class that fails against modern lockfiles.
+  return String(Math.max(...majors));
+}
+
+// Decide the Node the generated CI should use, preferring the project's own
+// declaration so CI's npm matches the dev's (a mismatch makes `npm ci` fail with
+// "missing from lock file" — a red gate unrelated to architecture). In order:
+//   1. .nvmrc / .node-version → setup-node's node-version-file (exact, best)
+//   2. package.json engines.node → its concrete major
+//   3. sibling workflows' node-version (highest major; excludes ark-check.yml)
+//   4. a current-LTS default
+export function detectCiNode(root) {
+  for (const file of ['.nvmrc', '.node-version']) {
+    if (fs.existsSync(path.join(root, file))) return { kind: 'file', value: file };
+  }
+  const enginesNode = readPackageJson(root)?.engines?.node;
+  if (typeof enginesNode === 'string') {
+    const major = enginesNode.match(/\d+/)?.[0];
+    if (major) return { kind: 'version', value: major };
+  }
+  const fromWorkflows = detectNodeMajorFromWorkflows(root);
+  if (fromWorkflows) return { kind: 'version', value: fromWorkflows };
+  return { kind: 'default', value: DEFAULT_CI_NODE_VERSION };
+}
+
+/**
+ * @param {{ name: string, install: string, run: string, cache: string, setup: string[] }} pm
+ * @param {{ kind: string, value: string }} ciNode
+ * @param {{ hasLintScript?: boolean, hasTypecheckScript?: boolean }} [quality]
+ */
+export function githubWorkflow(pm, ciNode, quality = {}) {
+  // pnpm/yarn setup (corepack enable) MUST run before actions/setup-node so the package
+  // manager is on PATH when setup-node's `cache: pnpm|yarn` tries to resolve the store —
+  // otherwise the cache step fails on a fresh runner ("Unable to locate executable file: pnpm").
+  const setupSteps = pm.setup.map((command) => `      - run: ${command}`).join('\n');
+  // node-version-file keeps CI locked to the dev's exact toolchain; an explicit
+  // version comes from engines.node; the default carries a hint for the mismatch
+  // symptom since we can't know which npm wrote the lockfile.
+  const nodeSetup =
+    ciNode.kind === 'file'
+      ? `          node-version-file: ${ciNode.value}`
+      : ciNode.kind === 'version'
+        ? `          node-version: '${ciNode.value}'`
+        : `          # If the install step fails with "missing from lock file" / lockfile out
+          # of sync, your local package manager is newer than this Node's — add a
+          # .nvmrc with your Node version so CI matches the dev environment.
+          node-version: '${ciNode.value}'`;
+  // When package.json already has lint/typecheck, emit CI steps so deploy-path
+  // honesty matches local scripts (Next/CRA often run these in production build).
+  const install = pm.install || '';
+  const runPrefix = install.startsWith('pnpm')
+    ? 'pnpm run'
+    : install.startsWith('yarn')
+      ? 'yarn'
+      : install.startsWith('bun')
+        ? 'bun run'
+        : 'npm run';
+  const qualityBlock = [
+    quality.hasTypecheckScript
+      ? `      - name: Typecheck\n        run: ${runPrefix} typecheck`
+      : '',
+    quality.hasLintScript ? `      - name: Lint\n        run: ${runPrefix} lint` : '',
+  ]
+    .filter(Boolean)
+    .join('\n');
+  return `name: Ark architecture gate
+
+on:
+  pull_request:
+  push:
+    branches: [main, master]
+
+jobs:
+  ark-check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+${setupSteps ? `${setupSteps}\n` : ''}      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+${nodeSetup}
+          cache: ${pm.cache}
+      - name: Install dependencies
+        run: ${pm.install}
+${qualityBlock ? `${qualityBlock}\n` : ''}      - name: Ark architecture check
+        run: ${pm.run}
+`;
+}

package/bin/lib/deploy-path.mjs

@@ -0,0 +1,205 @@
+/**
+ * Production deploy-path quality signals (install modularization).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { readPackageJson, packageScriptsHaveTypecheck } from './gate-files.mjs';
+
+/**
+ * Production deploy path quality (universal — any consumer repo).
+ * Detects when the production build host runs ESLint / typecheck as part of
+ * `build` (e.g. Next.js "Linting and checking validity of types") so failures
+ * surface first on Vercel/Netlify/etc. unless CI/pre-merge runs the same checks.
+ * Framework signals only (deps + scripts + config) — never project-specific.
+ *
+ * @returns {{
+ *   embedsLintInBuild: boolean,
+ *   embedsTypecheckInBuild: boolean,
+ *   engines: string[],
+ *   hasLintScript: boolean,
+ *   hasTypecheckScript: boolean,
+ *   ciRunsLint: boolean,
+ *   ciRunsTypecheck: boolean,
+ *   eslintIgnoreDuringBuilds: boolean,
+ * }}
+ */
+export function detectDeployPathQuality(root) {
+  const pkg = readPackageJson(root) || {};
+  const deps = {
+    ...(pkg.dependencies && typeof pkg.dependencies === 'object' ? pkg.dependencies : {}),
+    ...(pkg.devDependencies && typeof pkg.devDependencies === 'object' ? pkg.devDependencies : {}),
+    ...(pkg.peerDependencies && typeof pkg.peerDependencies === 'object' ? pkg.peerDependencies : {}),
+  };
+  const scripts =
+    pkg.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {};
+  const buildScript = typeof scripts.build === 'string' ? scripts.build : '';
+
+  const engines = [];
+  // Next.js production build runs ESLint + typecheck by default (unless opted out).
+  if (deps.next || /\bnext\s+build\b/.test(buildScript)) engines.push('next');
+  // Nuxt 3+ can lint via modules; only flag when build clearly invokes nuxt build + eslint tooling present.
+  if ((deps.nuxt || deps['nuxt3'] || /\bnuxt\s+build\b/.test(buildScript)) && (deps.eslint || hasEslintConfig(root))) {
+    engines.push('nuxt');
+  }
+  // Create React App historically failed build on ESLint errors.
+  if (deps['react-scripts'] || /\breact-scripts\s+build\b/.test(buildScript)) engines.push('cra');
+
+  const eslintIgnoreDuringBuilds = engines.includes('next') && nextIgnoresEslintDuringBuilds(root);
+  const embedsLintInBuild = engines.length > 0 && !eslintIgnoreDuringBuilds;
+  // Next still typechecks during build even when eslint.ignoreDuringBuilds is true.
+  const embedsTypecheckInBuild = engines.includes('next') || engines.includes('nuxt');
+
+  const scriptHasLint = (s) =>
+    Boolean(
+      s &&
+        ((typeof s.lint === 'string' && s.lint.trim()) ||
+          (typeof s.eslint === 'string' && s.eslint.trim()) ||
+          (typeof s['lint:ci'] === 'string' && s['lint:ci'].trim()) ||
+          (typeof s['check:lint'] === 'string' && s['check:lint'].trim()))
+    );
+
+  let hasLintScript = scriptHasLint(scripts);
+  let hasTypecheckScript = packageScriptsHaveTypecheck(scripts);
+  const packageLintScripts = [];
+  // Monorepo: package-level scripts count (apps/web, packages/ui, …).
+  try {
+    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+      const candidates = [path.join(root, entry.name)];
+      // one more level: packages/foo
+      try {
+        for (const child of fs.readdirSync(path.join(root, entry.name), { withFileTypes: true })) {
+          if (child.isDirectory() && !child.name.startsWith('.')) {
+            candidates.push(path.join(root, entry.name, child.name));
+          }
+        }
+      } catch {
+        /* ignore */
+      }
+      for (const dir of candidates) {
+        const pj = path.join(dir, 'package.json');
+        if (!fs.existsSync(pj)) continue;
+        try {
+          const nested = JSON.parse(fs.readFileSync(pj, 'utf8'));
+          const ns = nested.scripts && typeof nested.scripts === 'object' ? nested.scripts : {};
+          if (scriptHasLint(ns)) {
+            hasLintScript = true;
+            packageLintScripts.push(path.relative(root, dir).split(path.sep).join('/'));
+          }
+          if (packageScriptsHaveTypecheck(ns)) hasTypecheckScript = true;
+          const nd = {
+            ...(nested.dependencies || {}),
+            ...(nested.devDependencies || {}),
+          };
+          if (nd.next && !engines.includes('next')) engines.push('next');
+        } catch {
+          /* ignore */
+        }
+      }
+    }
+  } catch {
+    /* ignore */
+  }
+
+  const ciTexts = collectCiWorkflowTexts(root);
+  const ciJoined = ciTexts.join('\n');
+  const ciRunsLint =
+    ciTexts.length > 0 &&
+    (/\bnpm\s+run\s+lint\b/i.test(ciJoined) ||
+      /\bpnpm\s+(?:run\s+)?lint\b/i.test(ciJoined) ||
+      /\byarn\s+(?:run\s+)?lint\b/i.test(ciJoined) ||
+      /\bbun\s+run\s+lint\b/i.test(ciJoined) ||
+      /\beslint\b/i.test(ciJoined) ||
+      /\blint:ci\b/i.test(ciJoined) ||
+      /\bcheck:lint\b/i.test(ciJoined) ||
+      // package-level: working-directory + lint, or path/filter lint
+      (packageLintScripts.length > 0 &&
+        packageLintScripts.some((p) => ciJoined.includes(p) && /lint/i.test(ciJoined))));
+  const ciRunsTypecheck =
+    ciTexts.length > 0 &&
+    (/\btypecheck\b/i.test(ciJoined) ||
+      /\btype-check\b/i.test(ciJoined) ||
+      /\bcheck:types\b/i.test(ciJoined) ||
+      /\btsc\s+--noEmit\b/i.test(ciJoined));
+
+  return {
+    embedsLintInBuild,
+    embedsTypecheckInBuild,
+    engines,
+    hasLintScript,
+    hasTypecheckScript,
+    ciRunsLint,
+    ciRunsTypecheck,
+    eslintIgnoreDuringBuilds,
+    hasCiWorkflows: ciTexts.length > 0,
+    packageLintScripts,
+  };
+}
+
+function hasEslintConfig(root) {
+  return [
+    'eslint.config.mjs',
+    'eslint.config.js',
+    'eslint.config.cjs',
+    'eslint.config.ts',
+    '.eslintrc.json',
+    '.eslintrc.cjs',
+    '.eslintrc.js',
+    '.eslintrc.yml',
+    '.eslintrc.yaml',
+  ].some((f) => fs.existsSync(path.join(root, f)));
+}
+
+/** next.config.* eslint.ignoreDuringBuilds: true → production build will not fail on ESLint. */
+function nextIgnoresEslintDuringBuilds(root) {
+  const names = [
+    'next.config.ts',
+    'next.config.mts',
+    'next.config.js',
+    'next.config.mjs',
+    'next.config.cjs',
+  ];
+  for (const name of names) {
+    const file = path.join(root, name);
+    if (!fs.existsSync(file)) continue;
+    try {
+      const text = fs.readFileSync(file, 'utf8');
+      // Common patterns: ignoreDuringBuilds: true | ignoreDuringBuilds: true,
+      if (/ignoreDuringBuilds\s*:\s*true/.test(text)) return true;
+    } catch {
+      /* ignore */
+    }
+  }
+  return false;
+}
+
+function collectCiWorkflowTexts(root) {
+  const texts = [];
+  const pushFile = (rel) => {
+    try {
+      const full = path.join(root, rel);
+      if (fs.existsSync(full) && fs.statSync(full).isFile()) {
+        texts.push(fs.readFileSync(full, 'utf8'));
+      }
+    } catch {
+      /* ignore */
+    }
+  };
+  pushFile('.gitlab-ci.yml');
+  pushFile('bitbucket-pipelines.yml');
+  pushFile('azure-pipelines.yml');
+  pushFile('.circleci/config.yml');
+  const wfDir = path.join(root, '.github', 'workflows');
+  try {
+    if (fs.existsSync(wfDir)) {
+      for (const f of fs.readdirSync(wfDir)) {
+        if (!/\.ya?ml$/i.test(f)) continue;
+        pushFile(path.join('.github', 'workflows', f));
+      }
+    }
+  } catch {
+    /* ignore */
+  }
+  return texts;
+}
+