infra-kit 0.1.102 → 0.1.107

package/eslint.config.js

@@ -1,3 +1,3 @@
-import config from '@pkg/eslint-config'
+import config from '@wl/eslint-config'
 
 export default config()

package/infra-kit.config.ts

@@ -0,0 +1,5 @@
+import { defineConfig } from 'infra-kit'
+
+export default defineConfig(() => {
+  return {}
+})

package/package.json

@@ -1,13 +1,19 @@
 {
   "name": "infra-kit",
   "type": "module",
-  "version": "0.1.102",
+  "version": "0.1.107",
   "description": "infra-kit",
-  "main": "dist/cli.js",
-  "module": "dist/cli.js",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/entry/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/entry/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
   "bin": {
-    "infra-kit": "dist/cli.js",
-    "ik": "dist/cli.js"
+    "infra-kit": "dist/cli.js"
   },
   "engines": {
     "node": ">=24.x"
@@ -15,6 +21,7 @@
   "scripts": {
     "inspector": "npx @modelcontextprotocol/inspector node ./dist/mcp.js --debug",
     "build": "pnpm run clean-artifacts && node ./scripts/build.js",
+    "check": "node ./dist/cli.js check",
     "clean-artifacts": "rm -rf dist",
     "clean-cache": "rm -rf node_modules/.cache .eslintcache tsconfig.tsbuildinfo .turbo .swc",
     "prettier-fix": "pnpm exec prettier **/* --write --no-error-on-unmatched-pattern --log-level silent --ignore-path ../../../.prettierignore",
@@ -30,21 +37,21 @@
     "fix": "pnpm run prettier-fix && pnpm run eslint-fix && pnpm run qa"
   },
   "dependencies": {
-    "@inquirer/checkbox": "^5.1.5",
-    "@inquirer/confirm": "^6.0.13",
-    "@inquirer/select": "^5.1.5",
+    "@inquirer/checkbox": "^5.2.1",
+    "@inquirer/confirm": "^6.1.1",
+    "@inquirer/select": "^5.2.1",
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "commander": "^14.0.3",
+    "commander": "^15.0.0",
     "pino": "^10.3.1",
     "pino-pretty": "^13.1.3",
     "yaml": "^2.9.0",
-    "zod": "^3.25.76",
+    "zod": "^4.4.3",
     "zx": "^8.8.5"
   },
   "devDependencies": {
-    "@pkg/eslint-config": "workspace:*",
-    "@pkg/vitest-config": "workspace:*",
-    "esbuild": "^0.28.0",
+    "@wl/eslint-config": "workspace:*",
+    "@wl/vitest-config": "workspace:*",
+    "esbuild": "^0.28.1",
     "typescript": "^6.0.3"
   }
 }

package/scripts/build.js

@@ -1,4 +1,6 @@
+/* eslint-disable sonarjs/no-os-command-from-path */
 import * as esbuild from 'esbuild'
+import { execFileSync } from 'node:child_process'
 import fs from 'node:fs'
 import { dirname, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
@@ -8,10 +10,14 @@ import packageJson from '../package.json' with { type: 'json' }
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
 
-const OUT_DIR = resolve(__dirname, '../dist')
-const ENTRY_DIR = resolve(__dirname, '../src/entry')
+const PKG_DIR = resolve(__dirname, '..')
+const OUT_DIR = resolve(PKG_DIR, 'dist')
+const ENTRY_DIR = resolve(PKG_DIR, 'src/entry')
 
-const entryPoints = fs.readdirSync(ENTRY_DIR).map((file) => resolve(ENTRY_DIR, file))
+// 1. Bundle the JavaScript with esbuild (fast, but cannot emit .d.ts files).
+const entryPoints = fs.readdirSync(ENTRY_DIR).map((file) => {
+  return resolve(ENTRY_DIR, file)
+})
 
 await esbuild.build({
   entryPoints,
@@ -34,3 +40,26 @@ for (const entryPoint of entryPoints) {
 
   console.log('✅ Build was completed successfully: ', fileName, '-', +(stat.size / 1024 / 1024).toPrecision(3), 'MB')
 }
+
+// 2. Emit the public type declarations with tsc (esbuild does not generate them).
+//    The library entry (src/entry/index.ts) only re-exports the package-config
+//    API via relative imports, so tsc needs no project config — a direct CLI
+//    call replaces the separate tsconfig.build.json. `--ignoreConfig` is
+//    required because tsconfig.json is present alongside the input file.
+execFileSync(
+  'tsc',
+  [
+    'src/entry/index.ts',
+    '--ignoreConfig',
+    '--declaration',
+    '--emitDeclarationOnly',
+    '--rootDir',
+    'src',
+    '--outDir',
+    'dist',
+    '--skipLibCheck',
+  ],
+  { cwd: PKG_DIR, stdio: 'inherit' },
+)
+
+console.log('✅ Type declarations emitted: dist/entry/index.d.ts')

package/src/.omc/state/sessions/0a58307d-2a37-4c69-851c-83a646502d62/pre-tool-advisory-throttle.json

@@ -0,0 +1,18 @@
+{
+  "version": 1,
+  "entries": {
+    "79a93d4a2f8f50b95f852280616242fee1855dc99a3c75211917f55e72e95fae": {
+      "last_emitted_at_ms": 1781185365793,
+      "message": "Use parallel execution for independent tasks. Use run_in_background for long operations (npm install, builds, tests)."
+    },
+    "445ed27a3872b681d98190bae61ccb84954e1bc4e140df5370be958dee776b3a": {
+      "last_emitted_at_ms": 1781185292480,
+      "message": "Verify changes work after editing. Test functionality before marking complete."
+    },
+    "466399dafa2d20f60587180bad0a07358eb7f2bce724df0ff682f038ad33f5ad": {
+      "last_emitted_at_ms": 1781185283907,
+      "message": "Read multiple files in parallel when possible for faster analysis."
+    }
+  },
+  "updated_at": "2026-06-11T13:42:45.793Z"
+}

package/src/commands/.omc/state/sessions/afc6290b-40d3-4bef-b3b6-14484c034ab9/pre-tool-advisory-throttle.json

@@ -0,0 +1,14 @@
+{
+  "version": 1,
+  "entries": {
+    "79a93d4a2f8f50b95f852280616242fee1855dc99a3c75211917f55e72e95fae": {
+      "last_emitted_at_ms": 1781510589151,
+      "message": "Use parallel execution for independent tasks. Use run_in_background for long operations (npm install, builds, tests)."
+    },
+    "466399dafa2d20f60587180bad0a07358eb7f2bce724df0ff682f038ad33f5ad": {
+      "last_emitted_at_ms": 1781510561764,
+      "message": "Read multiple files in parallel when possible for faster analysis."
+    }
+  },
+  "updated_at": "2026-06-15T08:03:09.151Z"
+}

package/src/commands/.omc/state/sessions/c967c819-3d1c-447b-ab48-56a8448ef9f8/pre-tool-advisory-throttle.json

@@ -0,0 +1,18 @@
+{
+  "version": 1,
+  "entries": {
+    "79a93d4a2f8f50b95f852280616242fee1855dc99a3c75211917f55e72e95fae": {
+      "last_emitted_at_ms": 1780905267223,
+      "message": "Use parallel execution for independent tasks. Use run_in_background for long operations (npm install, builds, tests)."
+    },
+    "445ed27a3872b681d98190bae61ccb84954e1bc4e140df5370be958dee776b3a": {
+      "last_emitted_at_ms": 1780905232864,
+      "message": "Verify changes work after editing. Test functionality before marking complete."
+    },
+    "466399dafa2d20f60587180bad0a07358eb7f2bce724df0ff682f038ad33f5ad": {
+      "last_emitted_at_ms": 1780905206915,
+      "message": "Read multiple files in parallel when possible for faster analysis."
+    }
+  },
+  "updated_at": "2026-06-08T07:54:27.223Z"
+}

package/src/commands/audit/__tests__/audit.test.ts

@@ -0,0 +1,59 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+
+import { audit, auditMcpTool } from '../audit'
+
+const tmpDirs: string[] = []
+
+const makeTmpPackage = (config: string, packageJson: Record<string, unknown>): string => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'audit-cmd-'))
+
+  tmpDirs.push(dir)
+  fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify(packageJson))
+  fs.writeFileSync(path.join(dir, 'infra-kit.config.ts'), config)
+
+  return dir
+}
+
+afterEach(() => {
+  while (tmpDirs.length > 0) {
+    const dir = tmpDirs.pop()
+
+    if (dir) {
+      fs.rmSync(dir, { recursive: true, force: true })
+    }
+  }
+})
+
+describe('audit', () => {
+  it('passes a package that satisfies its resolved rules', async () => {
+    const dir = makeTmpPackage('export default { requiredScripts: [], requiredFiles: [] }', {
+      name: '@x/ok',
+      type: 'module',
+    })
+
+    const result = await audit({ cwd: dir })
+
+    expect(result.structuredContent.allPassed).toBe(true)
+    expect(result.structuredContent.packages[0]?.name).toBe('@x/ok')
+  })
+
+  it('fails a package missing infra-kit.config.ts', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'audit-cmd-'))
+
+    tmpDirs.push(dir)
+    fs.writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ name: '@x/no-config', type: 'module' }))
+
+    const result = await audit({ cwd: dir })
+
+    expect(result.structuredContent.allPassed).toBe(false)
+  })
+})
+
+describe('mCP tool registration', () => {
+  it('exposes the canonical `audit` tool', () => {
+    expect(auditMcpTool.name).toBe('audit')
+  })
+})

package/src/commands/audit/audit.ts

@@ -0,0 +1,177 @@
+import path from 'node:path'
+import process from 'node:process'
+import { z } from 'zod'
+
+import { getProjectRoot } from 'src/lib/git-utils'
+import { logger } from 'src/lib/logger'
+import { ROOT_DEFAULT_RULES } from 'src/lib/package-config'
+import type { ResolvedPackageRules } from 'src/lib/package-config'
+import { discoverPackages, pathExists, validatePackage } from 'src/lib/package-validator'
+import type { PackageValidationResult } from 'src/lib/package-validator'
+import { defineMcpTool, textContent } from 'src/types'
+
+// TODO [DO]: extract `audit` into its own standalone CLI tool, decoupled from infra-kit.
+
+interface AuditOptions {
+  /** Audit every non-vendor workspace package instead of just the current one. */
+  all?: boolean
+  /** Audit the monorepo root (turbo pipeline + root commands) instead of a package. */
+  root?: boolean
+  /** Directory to resolve the current package from. Defaults to `process.cwd()`. */
+  cwd?: string
+}
+
+/** A directory to audit plus the under-the-hood defaults that apply to it. */
+interface AuditTarget {
+  dir: string
+  baseline?: Readonly<ResolvedPackageRules>
+}
+
+/**
+ * Walk upward from `start` to the nearest directory containing a package.json.
+ * Used so `infra-kit audit` (no `--all`) targets the package whose package.json
+ * script invoked it, regardless of the exact working directory.
+ *
+ * @example
+ * await findPackageRoot('/repo/packages/serverless-config/src')
+ * // => '/repo/packages/serverless-config'
+ */
+const findPackageRoot = async (start: string): Promise<string> => {
+  let current = path.resolve(start)
+
+  while (current !== path.dirname(current)) {
+    if (await pathExists(path.join(current, 'package.json'))) {
+      return current
+    }
+
+    current = path.dirname(current)
+  }
+
+  if (await pathExists(path.join(current, 'package.json'))) {
+    return current
+  }
+
+  throw new Error(`No package.json found in or above ${start}`)
+}
+
+/**
+ * Resolve which directories to audit, and the baseline defaults each uses:
+ * `root` → the monorepo root with {@link ROOT_DEFAULT_RULES}; `all` → every
+ * discovered non-vendor package; otherwise the package walked up from cwd.
+ */
+const resolveTargets = async (options: AuditOptions): Promise<AuditTarget[]> => {
+  if (options.root) {
+    return [{ dir: await getProjectRoot(), baseline: ROOT_DEFAULT_RULES }]
+  }
+
+  if (options.all) {
+    const dirs = await discoverPackages(await getProjectRoot())
+
+    return dirs.map((dir) => {
+      return { dir }
+    })
+  }
+
+  return [{ dir: await findPackageRoot(options.cwd ?? process.cwd()) }]
+}
+
+/**
+ * Print a package's audit result as doctor-style `[PASS]`/`[FAIL]` lines.
+ */
+const logResult = (result: PackageValidationResult): void => {
+  const header = result.passed ? 'PASS' : 'FAIL'
+
+  logger.info(`\n${result.packageName} — ${header}`)
+
+  for (const check of result.checks) {
+    const icon = check.status === 'pass' ? '[PASS]' : '[FAIL]'
+
+    logger.info(`  ${icon} ${check.name}: ${check.message}`)
+  }
+}
+
+/**
+ * Audit the monorepo root (`root`), every non-vendor workspace package (`all`),
+ * or the package resolved by walking up from the working directory (default —
+ * the shape used by a package's `"check": "infra-kit audit"` script). The
+ * returned `structuredContent.allPassed` lets the CLI set a non-zero exit code so
+ * the audit fails CI; this function never calls `process.exit` so the MCP tool
+ * can reuse it.
+ *
+ * @example
+ * // CLI inside packages/serverless-config: `infra-kit audit`
+ * await audit()              // audits the current package
+ * await audit({ all: true }) // audits every non-vendor workspace package
+ * await audit({ root: true }) // audits the monorepo root (turbo + root commands)
+ */
+export const audit = async (options: AuditOptions = {}) => {
+  const targets = await resolveTargets(options)
+
+  const results: PackageValidationResult[] = []
+
+  for (const target of targets) {
+    results.push(await validatePackage(target.dir, target.baseline))
+  }
+
+  for (const result of results) {
+    logResult(result)
+  }
+
+  const allPassed = results.every((result) => {
+    return result.passed
+  })
+
+  logger.info(`\n${allPassed ? '✅ All valid' : '❌ Audit failed'} (${results.length} checked)`)
+
+  const structuredContent = {
+    allPassed,
+    packages: results.map((result) => {
+      return {
+        name: result.packageName,
+        passed: result.passed,
+        checks: result.checks,
+      }
+    }),
+  }
+
+  return {
+    content: textContent(JSON.stringify(structuredContent, null, 2)),
+    structuredContent,
+  }
+}
+
+const auditInputSchema = {
+  all: z.boolean().optional().describe('Audit every non-vendor workspace package'),
+  root: z.boolean().optional().describe('Audit the monorepo root (turbo pipeline + root commands)'),
+}
+
+const auditOutputSchema = {
+  allPassed: z.boolean().describe('Whether every audited package passed all checks'),
+  packages: z
+    .array(
+      z.object({
+        name: z.string(),
+        passed: z.boolean(),
+        checks: z.array(
+          z.object({
+            name: z.string(),
+            status: z.enum(['pass', 'fail']),
+            message: z.string(),
+          }),
+        ),
+      }),
+    )
+    .describe('Per-package check results'),
+}
+
+// MCP Tool Registration
+export const auditMcpTool = defineMcpTool({
+  name: 'audit',
+  description:
+    'Audit packages against infra-kit.config.ts rules (config present and valid, required scripts, required files, and turbo tasks for the root). Defaults to the current package; all=true audits every non-vendor workspace package; root=true audits the monorepo root.',
+  inputSchema: auditInputSchema,
+  outputSchema: auditOutputSchema,
+  handler: (params) => {
+    return audit({ all: params.all, root: params.root })
+  },
+})

package/src/commands/audit/index.ts

@@ -0,0 +1 @@
+export { audit, auditMcpTool } from './audit'

package/src/commands/config/config.ts

@@ -31,7 +31,7 @@ const fileExists = async (filePath: string): Promise<boolean> => {
  *
  * @example
  * // os.homedir() === '/Users/arthur'
- * tildify('/Users/arthur/.infra-kit/config.yml') // => '~/.infra-kit/config.yml'
+ * tildify('/Users/arthur/.infra-kit/config.json') // => '~/.infra-kit/config.json'
  * tildify('/etc/hosts')                          // => '/etc/hosts'
  */
 const tildify = (filePath: string): string => {
@@ -49,9 +49,9 @@ const tildify = (filePath: string): string => {
  * // CLI: `infra-kit config path`
  * // INFO: Project name: api
  * // INFO: Config merge chain (later overrides earlier):
- * // INFO:   [✓] project (committed)    ~/projects/api/infra-kit.yml
- * // INFO:   [ ] user global            ~/.infra-kit/config.yml
- * // INFO:   [✓] user project           ~/.infra-kit/projects/api/infra-kit.yml
+ * // INFO:   [✓] project (committed)    ~/projects/api/infra-kit.json
+ * // INFO:   [ ] user global            ~/.infra-kit/config.json
+ * // INFO:   [✓] user project           ~/.infra-kit/projects/api/infra-kit.json
  */
 export const configPath = async (): Promise<ToolsExecutionResult> => {
   const paths = await getInfraKitConfigPaths()
@@ -95,7 +95,8 @@ export const configPath = async (): Promise<ToolsExecutionResult> => {
  *
  * @example
  * // CLI: `infra-kit config edit`
- * // first run — creates ~/.infra-kit/projects/api/infra-kit.yml from a stub, then $EDITOR opens it
+ * // first run — creates ~/.infra-kit/projects/api/infra-kit.json ({}) + a sibling
+ * //             infra-kit.example.jsonc reference, then $EDITOR opens the .json
  * // subsequent runs — opens the existing file as-is
  */
 export const configEdit = async (): Promise<ToolsExecutionResult> => {
@@ -105,9 +106,15 @@ export const configEdit = async (): Promise<ToolsExecutionResult> => {
   await fs.mkdir(path.dirname(paths.userProject), { recursive: true })
 
   if (!(await fileExists(paths.userProject))) {
-    const stub = `# infra-kit user override for ${paths.projectName} — ~/.infra-kit/projects/${paths.projectName}/infra-kit.yml\n#\n# Layer 3 (highest precedence) of the config merge chain. Shallow-merged on\n# top of <repo>/infra-kit.yml and ~/.infra-kit/config.yml — top-level keys\n# (environments, envManagement, ide, taskManager, worktrees) replace wholesale.\n`
+    // JSON can't carry comments, so seed an empty-but-valid config and drop the
+    // annotated guidance next to it in a non-loaded .example.jsonc the loader
+    // never reads (it only globs the three exact `infra-kit.json` filenames).
+    const examplePath = exampleSiblingPath(paths.userProject)
 
-    await fs.writeFile(paths.userProject, stub, 'utf-8')
+    await fs.writeFile(paths.userProject, '{}\n', 'utf-8')
+    await fs.writeFile(examplePath, buildUserProjectExample(paths.projectName), 'utf-8')
+
+    logger.info(`Created ${tildify(paths.userProject)} — see ${tildify(examplePath)} for the annotated reference.`)
   }
 
   logger.info(`Opening ${tildify(paths.userProject)} in ${editor}`)
@@ -123,3 +130,38 @@ export const configEdit = async (): Promise<ToolsExecutionResult> => {
     structuredContent,
   }
 }
+
+/**
+ * Derive the non-loaded `.example.jsonc` sibling for a config path.
+ *
+ * @example
+ * exampleSiblingPath('/u/.infra-kit/projects/api/infra-kit.json')
+ * // => '/u/.infra-kit/projects/api/infra-kit.example.jsonc'
+ */
+const exampleSiblingPath = (jsonPath: string): string => {
+  return jsonPath.replace(/\.json$/, '.example.jsonc')
+}
+
+/**
+ * Annotated JSONC reference for the user-scope per-project override layer.
+ * Written alongside the real `{}` config so the guidance the old YAML stub
+ * carried in comments survives the move to JSON.
+ *
+ * @example
+ * buildUserProjectExample('api')
+ * // => '// infra-kit user override for api …\n{ … }\n'
+ */
+const buildUserProjectExample = (projectName: string): string => {
+  return `// infra-kit user override for ${projectName} — ~/.infra-kit/projects/${projectName}/infra-kit.json
+//
+// Layer 3 (highest precedence) of the config merge chain. Shallow-merged on top
+// of <repo>/infra-kit.json and ~/.infra-kit/config.json — top-level keys
+// (environments, envManagement, ide, taskManager, worktrees) replace wholesale.
+//
+// This .example.jsonc is reference only — it is NOT loaded. Put real overrides
+// in the sibling infra-kit.json (strict JSON: no comments, double-quoted keys).
+{
+  // "worktrees": { "openInGithubDesktop": false, "openInCmux": true }
+}
+`
+}

package/src/commands/doctor/__tests__/agent-files.test.ts

@@ -0,0 +1,110 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { writeAgentFiles } from 'src/commands/init/agent-files'
+import { getProjectRoot, getRepoName } from 'src/lib/git-utils'
+
+import { checkAgentFiles } from '../doctor'
+
+vi.mock('src/lib/git-utils', () => {
+  return {
+    getProjectRoot: vi.fn(),
+    getRepoName: vi.fn(),
+  }
+})
+
+const writeFile = (filePath: string, content: string): void => {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true })
+  fs.writeFileSync(filePath, content, 'utf-8')
+}
+
+const withTmpRepo = async (fn: (tmp: string) => Promise<void>, opts: { repo?: boolean } = {}): Promise<void> => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'infra-kit-doctor-agents-test-'))
+
+  vi.mocked(getProjectRoot).mockResolvedValue(tmp)
+  vi.mocked(getRepoName).mockResolvedValue(path.basename(tmp))
+
+  if (opts.repo !== false) {
+    writeFile(path.join(tmp, 'infra-kit.json'), '{"environments":["dev"]}\n')
+  }
+
+  try {
+    await fn(tmp)
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true })
+  }
+}
+
+const statusOf = (checks: { name: string; status: string }[], name: string): string | undefined => {
+  return checks.find((c) => {
+    return c.name === name
+  })?.status
+}
+
+describe('checkAgentFiles', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  afterEach(() => {
+    vi.clearAllMocks()
+  })
+
+  it('returns no checks outside an infra-kit repo (never crashes)', async () => {
+    await withTmpRepo(
+      async () => {
+        await expect(checkAgentFiles()).resolves.toEqual([])
+      },
+      { repo: false },
+    )
+  })
+
+  it('passes all three checks right after init runs the agent-files step', async () => {
+    await withTmpRepo(async () => {
+      await writeAgentFiles()
+
+      const checks = await checkAgentFiles()
+
+      expect(statusOf(checks, 'AGENTS.md block')).toBe('pass')
+      expect(statusOf(checks, 'CLAUDE.md import')).toBe('pass')
+      expect(statusOf(checks, '.cursor/rules block')).toBe('pass')
+    })
+  })
+
+  it('flags AGENTS.md present but CLAUDE.md import removed', async () => {
+    await withTmpRepo(async (tmp) => {
+      await writeAgentFiles()
+      // User deletes CLAUDE.md (drops the @AGENTS.md import) but keeps AGENTS.md.
+      fs.rmSync(path.join(tmp, 'CLAUDE.md'))
+
+      const checks = await checkAgentFiles()
+
+      expect(statusOf(checks, 'AGENTS.md block')).toBe('pass')
+      expect(statusOf(checks, 'CLAUDE.md import')).toBe('fail')
+    })
+  })
+
+  it('flags a missing .cursor/rules block', async () => {
+    await withTmpRepo(async (tmp) => {
+      await writeAgentFiles()
+      fs.rmSync(path.join(tmp, '.cursor', 'rules', 'infra-kit.mdc'))
+
+      const checks = await checkAgentFiles()
+
+      expect(statusOf(checks, '.cursor/rules block')).toBe('fail')
+    })
+  })
+
+  it('flags a missing AGENTS.md block', async () => {
+    await withTmpRepo(async (tmp) => {
+      await writeAgentFiles()
+      fs.rmSync(path.join(tmp, 'AGENTS.md'))
+
+      const checks = await checkAgentFiles()
+
+      expect(statusOf(checks, 'AGENTS.md block')).toBe('fail')
+    })
+  })
+})