@webpresso/agent-kit 0.21.5 → 0.24.0

package/catalog/agent/rules/public-package-safety.md

@@ -9,7 +9,7 @@ related:
   - package-conventions
   - repo-restrictions
 created: '2026-05-26'
-last_reviewed: '2026-05-26'
+last_reviewed: '2026-05-31'
 paths:
   - 'package.json'
   - '.npmignore'
@@ -54,3 +54,26 @@ publish workflow, registry, or catalog assets:
 
 If the tarball includes a denied class of content, the package is not ready to
 publish. Fix the package surface instead of documenting the leak as acceptable.
+
+## Shared deploy-contract surfaces stay provider-neutral
+
+If a public package or template documents the approved Durable Object preview
+lanes contract, keep the shared surface policy-only:
+
+- treat `dev`, `preview_main`, `preview_pr_<n>`, and `prd` as internal lane
+  IDs, not as Cloudflare-facing environment names;
+- derive provider env names separately and make them dash-safe;
+- document that Durable Object-backed previews must not depend on Preview
+  URLs; the default is custom-domain environment previews, with
+  `workers_dev_env` reserved for explicit exception cases;
+- keep the canonical production release metadata path at
+  `infra/release-metadata.production.json`;
+- require the consuming repo's workflow/verifier to fail closed for
+  migration-bearing Durable Object releases;
+- keep provider-specific plumbing, secrets, bindings, and release mechanics
+  out of shared `@webpresso/agent-kit` code, docs, and examples.
+
+Shared packages may define the contract and the guardrail names
+(`verify:deploy-contract`, metadata path, internal lane IDs), but the
+provider-specific implementation belongs in the consuming repo that owns the
+deployment target.

package/catalog/agent/skills/pll/SKILL.md

@@ -81,5 +81,6 @@ When no explicit task list is supplied, ground lane selection in `wp blueprint l
 ```bash
 /pll "lint auth, lint utils, typecheck api [depends: lint auth], test api [depends: typecheck api]"
 /pll tasks.md --max=6
+/pll blueprints/in-progress/new-launch.md
 /pll blueprints/in-progress/new-launch/_overview.md
 ```

package/catalog/base-kit/.github/workflows/ci.webpresso.yml.tmpl

@@ -64,3 +64,36 @@ jobs:
           WP="$(pwd)/node_modules/.bin/wp"
           [ -x "$WP" ] || WP=wp
           "$WP" audit guardrails
+
+  deploy-contract:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: pnpm/action-setup@v6
+      - uses: actions/setup-node@v5
+        with:
+          node-version: '24.16.0'
+          cache: pnpm
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - run: pnpm install --frozen-lockfile
+      - name: Verify deploy-contract gate when production release metadata is present
+        run: |
+          set -euo pipefail
+
+          METADATA_PATH='infra/release-metadata.production.json'
+
+          if [ ! -f "$METADATA_PATH" ]; then
+            echo "No production release metadata present at $METADATA_PATH; skipping deploy-contract gate."
+            exit 0
+          fi
+
+          if ! node -e "const pkg=require('./package.json'); process.exit(pkg.scripts && pkg.scripts['verify:deploy-contract'] ? 0 : 1)"; then
+            echo "::error::Detected $METADATA_PATH but no verify:deploy-contract script."
+            echo "::error::Repos adopting the shared deploy contract must keep agent-kit provider-neutral and supply a repo-owned deploy verifier."
+            echo "::error::That verifier owns provider-specific env-name derivation, Preview-URL prohibitions for DO previews, and must fail closed for migration-bearing Durable Object releases."
+            exit 1
+          fi
+
+          pnpm run verify:deploy-contract

package/catalog/base-kit/stryker.config.ts.tmpl

@@ -1,7 +1,7 @@
-import { baseConfig } from '@webpresso/agent-kit/stryker'
+import { typescriptBaseConfig } from '@webpresso/agent-kit/stryker'
 
 export default {
-  ...baseConfig,
+  ...typescriptBaseConfig,
   thresholds: {
     high: 0,
     low: 0,

package/catalog/docs/templates/blueprint.md

@@ -21,6 +21,7 @@ tags: []
 - Draft slug: `{{slug}}`
 - Output path: `{{output_path}}`
 - Generated command: `wp blueprint new "{{description}}" --complexity {{complexity}}`
+- Default shape: flat file (`blueprints/<status>/<slug>.md`)
 - Validation scope: parser compliance before write
 
 ## Architecture Overview

package/catalog/docs/templates/blueprint.yaml

@@ -4,6 +4,7 @@ description: Blueprint template for features/initiatives
 notes:
   - 'This file describes the current preferred blueprint structure, not an immutable final schema.'
   - 'Repo-wide validity is determined by the live blueprint parser/audit rules, not by requiring every optional section below.'
+  - 'Default creation shape: blueprints/<status>/<slug>.md. Folder-based blueprints remain valid at blueprints/<status>/<slug>/_overview.md when sibling docs are needed.'
 
 frontmatter:
   required:
@@ -12,7 +13,7 @@ frontmatter:
       description: Must be exactly "blueprint"
     status:
       enum: [draft, planned, parked, in-progress, completed, archived]
-      description: Current plan status (must match folder placement)
+      description: Current plan status (must match lifecycle placement)
     complexity:
       enum: [XS, S, M, L, XL]
       description: Estimated complexity
@@ -81,21 +82,18 @@ sections:
 
 location:
   patterns:
-    - 'blueprints/*/_overview.md'
+    - 'blueprints/*/*.md'
     - 'blueprints/*/*/_overview.md'
-    - 'blueprints/*/*/*/_overview.md'
-    - 'blueprints/completed/*/_overview.md'
-    - 'blueprints/planned/*/_overview.md'
-    - 'blueprints/parked/*/_overview.md'
-    - 'blueprints/in-progress/*/_overview.md'
-    - 'blueprints/draft/*/_overview.md'
-  exclude:
-    - 'blueprints/draft/*.md' # Standalone draft trackers such as deferred backlog
+    - 'blueprints/completed/*.md'
+    - 'blueprints/planned/*.md'
+    - 'blueprints/parked/*.md'
+    - 'blueprints/in-progress/*.md'
+    - 'blueprints/draft/*.md'
 
 naming:
-  pattern: '_overview.md'
+  pattern: '<slug>.md or _overview.md'
   case: exact
-  notes: 'Use _overview.md for high-level summary. Detailed phases go in phase-N-name.md files.'
+  notes: 'Use <slug>.md by default. Use folder + _overview.md when the blueprint needs sibling markdown docs.'
 
 task_format:
   heading:

package/commands/blueprint.md

@@ -15,47 +15,12 @@ Use the focused blueprint MCP tools.
 - `wp_blueprint_task_verify` — mark a task `done` with evidence; accepts optional `request_id` and `head_at_ingest` for retry-safe verification
 - `wp_blueprint_promote` / `wp_blueprint_finalize` — accept optional `project_id` for nested-workspace disambiguation
 
-Mutation guidance:
+Guidance:
 
-- V1 structured authoring is limited to `wp_blueprint_put + wp_blueprint_transition`.
-- Use `request_id` on `wp_blueprint_create`, `wp_blueprint_put`,
-  `wp_blueprint_task_advance`, and `wp_blueprint_task_verify` when the caller
-  may retry the same request.
-- Prefer passing `project_id` from `wp_blueprint_projects` whenever the current
-  working directory can see more than one blueprint-bearing repo.
-- Carry `head_at_ingest` from `wp_blueprint_list`, `wp_blueprint_get`, or
-  `wp_blueprint_context` into `wp_blueprint_create`, `wp_blueprint_put`, and
-  other mutation calls when the caller needs stale-write protection across
-  retries or multi-agent handoff.
-- Reusing the same `request_id` with the same payload is idempotent.
-- Reusing the same `request_id` with a different payload is rejected.
-- If `head_at_ingest` is stale, the mutation is rejected and points the caller
-  back to a canonical `wp_*` refresh path.
-- `wp_blueprint_transition` uses `expected_version` (the current
-  `content_hash`) for blueprint-scoped optimistic concurrency.
-
-Deferred patch boundary:
-
-- `wp_blueprint_patch` is **not** part of the v1 canonical surface.
-- If/when added, the patch model must be **semantic**, not raw markdown
-  mutation.
-- Minimum deferred operations:
-  - `add_task`
-  - `update_task`
-  - `set_summary`
-  - `replace_decision`
-- Until then, whole-document `wp_blueprint_put` is the canonical authoring path.
-
-Deferred UI/editor boundary:
-
-- A future MCP Apps blueprint editor is an **enhancement**, not part of the v1
-  correctness path.
-- Any UI flow must layer on top of `wp_blueprint_put + wp_blueprint_transition`
-  instead of introducing a parallel write surface.
-- Hosts without MCP Apps support must still complete the full authoring flow
-  through the structured tools alone.
-- Minimum v2 editor contract:
-  - capability detection for MCP Apps support
-  - structured form/editor over the full blueprint document
-  - non-UI fallback guidance that routes back to `wp_blueprint_put` and
-    `wp_blueprint_transition`
+- Prefer `project_id` from `wp_blueprint_projects` when multiple repos are visible.
+- Use `request_id` for retry-safe mutations and reuse it only with the same payload.
+- Carry `head_at_ingest` from read/context tools into stale-write-sensitive mutations.
+- Author documents through `wp_blueprint_put`, then lifecycle with `wp_blueprint_transition`.
+- Deferred `wp_blueprint_patch` semantic ops (`add_task`, `update_task`, `set_summary`, `replace_decision`) are future layers; patch is **not** part of the v1 canonical surface.
+- MCP Apps editor support is a follow-on enhancement over `wp_blueprint_put` / `wp_blueprint_transition`.
+- Hosts without MCP Apps support keep using the structured tools above.

package/dist/esm/audit/blueprint-db-consistency.d.ts

@@ -7,7 +7,7 @@
  *
  * Checks (when enabled):
  * 1. Every `blueprints` row's `file_path` actually exists on disk.
- * 2. Every blueprint `_overview.md` on disk has a corresponding DB row.
+ * 2. Every canonical blueprint markdown file on disk has a corresponding DB row.
  * 3. `content_hash` in DB matches the current SHA-256 of the file content.
  */
 import type { RepoAuditResult } from './repo-guardrails.js';

package/dist/esm/audit/blueprint-db-consistency.js

@@ -7,13 +7,13 @@
  *
  * Checks (when enabled):
  * 1. Every `blueprints` row's `file_path` actually exists on disk.
- * 2. Every blueprint `_overview.md` on disk has a corresponding DB row.
+ * 2. Every canonical blueprint markdown file on disk has a corresponding DB row.
  * 3. `content_hash` in DB matches the current SHA-256 of the file content.
  */
 import { createHash } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
-import { glob } from 'glob';
+import { scanBlueprintDirectory } from '#service/scanner.js';
 const DB_PATH = path.join('.agent', '.blueprints.db');
 const _DISABLED_RESULT = {
     ok: true,
@@ -76,12 +76,10 @@ export async function auditBlueprintDbConsistency(cwd) {
         // 2: files on disk → verify each has a DB row
         // -----------------------------------------------------------------------
         const dbPaths = new Set(rows.map((r) => r.file_path));
-        // Blueprints follow blueprints/<status>/<slug>/_overview.md convention
-        const overviewFiles = await glob('blueprints/**/_overview.md', {
-            cwd,
-            absolute: false,
-            ignore: ['node_modules/**'],
-        });
+        const overviewFiles = scanBlueprintDirectory({
+            baseDir: path.join(cwd, 'blueprints'),
+            includeSpecialFolders: true,
+        }).map((entry) => path.relative(cwd, entry.path).replace(/\\/g, '/'));
         checked += overviewFiles.length;
         for (const rel of overviewFiles) {
             const normalised = rel.replace(/\\/g, '/');

package/dist/esm/audit/blueprint-lifecycle-sql.js

@@ -45,6 +45,16 @@ export async function auditBlueprintLifecycleSql(cwd) {
     const violations = [];
     let checked = 0;
     try {
+        const allBlueprints = db
+            .prepare('SELECT slug, status, file_path, progress_pct FROM blueprints')
+            .all();
+        if (allBlueprints.length === 0) {
+            const { auditBlueprintLifecycle } = await import('./repo-guardrails.js');
+            const markdownAudit = auditBlueprintLifecycle(cwd);
+            if (markdownAudit.checked > 0) {
+                return markdownAudit;
+            }
+        }
         // -----------------------------------------------------------------------
         // 1. in-progress blueprints with 0 tasks
         // -----------------------------------------------------------------------
@@ -68,9 +78,6 @@ export async function auditBlueprintLifecycleSql(cwd) {
         //    Derive the directory segment from the file_path and compare to status.
         //    Blueprint file_path convention: blueprints/<status>/<slug>/_overview.md
         // -----------------------------------------------------------------------
-        const allBlueprints = db
-            .prepare('SELECT slug, status, file_path, progress_pct FROM blueprints')
-            .all();
         checked += allBlueprints.length;
         for (const row of allBlueprints) {
             // Derive directory status from the path: second segment after 'blueprints/'

package/dist/esm/audit/cloudflare-deploy-contract.d.ts

@@ -0,0 +1,3 @@
+import type { RepoAuditResult } from './repo-guardrails.js';
+export declare function auditCloudflareDeployContract(root: string): Promise<RepoAuditResult>;
+//# sourceMappingURL=cloudflare-deploy-contract.d.ts.map

package/dist/esm/audit/cloudflare-deploy-contract.js

@@ -0,0 +1,80 @@
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { loadWebpressoConfigSafe } from '#e2e/load-host-adapter';
+function violation(file, message) {
+    return { file, message };
+}
+function readProductionMetadata(metadataPath) {
+    return JSON.parse(readFileSync(metadataPath, 'utf8'));
+}
+export async function auditCloudflareDeployContract(root) {
+    let loaded;
+    try {
+        loaded = await loadWebpressoConfigSafe({ cwd: root });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            ok: false,
+            title: 'Cloudflare deploy contract',
+            checked: 1,
+            violations: [violation(path.join(root, 'webpresso.config.ts'), message)],
+        };
+    }
+    const configPath = loaded?.configPath ?? path.join(root, 'webpresso.config.ts');
+    const cloudflare = loaded?.config.deploy?.cloudflare;
+    if (!cloudflare) {
+        return {
+            ok: true,
+            title: 'Cloudflare deploy contract',
+            checked: 0,
+            violations: [],
+        };
+    }
+    const violations = [];
+    const metadataPath = path.join(root, cloudflare.production.metadataPath);
+    if (!existsSync(metadataPath)) {
+        violations.push(violation(configPath, `shared deploy contract requires ${cloudflare.production.metadataPath} to exist`));
+    }
+    else {
+        try {
+            const metadata = readProductionMetadata(metadataPath);
+            if (metadata.durableObjectMigration === 'required' &&
+                metadata.rolloutMode !== 'direct') {
+                violations.push(violation(cloudflare.production.metadataPath, 'Durable Object migration releases must use rolloutMode "direct"'));
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            violations.push(violation(cloudflare.production.metadataPath, `production release metadata must be valid JSON: ${message}`));
+        }
+    }
+    for (const target of cloudflare.targets) {
+        const isDurableObjectTarget = (target.durableObjectBindings?.length ?? 0) > 0;
+        if (target.previewTransport === 'custom_domain_env' && !target.routeSpec) {
+            violations.push(violation(configPath, `target ${target.id} uses custom_domain_env but does not declare routeSpec`));
+        }
+        if (target.durableObjectBindings && target.durableObjectBindings.length === 0) {
+            violations.push(violation(configPath, `target ${target.id} declares durableObjectBindings but provides no env-specific bindings`));
+        }
+        if (isDurableObjectTarget && target.previewTransport !== 'custom_domain_env') {
+            violations.push(violation(configPath, `target ${target.id} is a Durable Object consumer and must use previewTransport "custom_domain_env"`));
+        }
+        if (isDurableObjectTarget && Object.keys(target.vars).length === 0) {
+            violations.push(violation(configPath, `target ${target.id} is a Durable Object consumer and must declare at least one env-specific var`));
+        }
+        if (isDurableObjectTarget && target.requiredSecrets.length === 0) {
+            violations.push(violation(configPath, `target ${target.id} is a Durable Object consumer and must declare at least one required secret name`));
+        }
+        if (target.storageMode === 'shared_via_script_name' && !target.blastRadiusDoc) {
+            violations.push(violation(configPath, `target ${target.id} uses shared_via_script_name without blastRadiusDoc`));
+        }
+    }
+    return {
+        ok: violations.length === 0,
+        title: 'Cloudflare deploy contract',
+        checked: 1 + cloudflare.targets.length,
+        violations,
+    };
+}
+//# sourceMappingURL=cloudflare-deploy-contract.js.map

package/dist/esm/audit/no-legacy-cli-bin.d.ts

@@ -0,0 +1,3 @@
+import type { RepoAuditResult } from './repo-guardrails.js';
+export declare function auditNoLegacyCliBin(rootDirectory?: string): RepoAuditResult;
+//# sourceMappingURL=no-legacy-cli-bin.d.ts.map

package/dist/esm/audit/no-legacy-cli-bin.js

@@ -0,0 +1,100 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+// `wp` remains the canonical public CLI in AGENTS.md. This audit only guards
+// retired compatibility aliases from leaking into active user-facing surfaces.
+const LEGACY_COMMAND_PATTERN = /\b(?:ak|cli2|wk)\s+[a-z][\w:-]*(?:\s+[a-z][\w:-]*)*/giu;
+const INTERNAL_HELPER_PATTERN = /\bwp-(?:pretool-guard|post-tool|stop-qa|guard-switch|sessionstart-routing|check-dev-link)\b/u;
+const REPLACEMENT_PATTERN = /\bwebpresso agent [a-z][\w:-]*(?: [a-z][\w:-]*)*/iu;
+const MIGRATION_MARKER_PATTERN = /\b(?:current-state|migration-only|replacement|future)\b/iu;
+// Scan current user-facing/documentation inputs only. Source tests and completed/parked
+// blueprints intentionally preserve historical command names as regression fixtures
+// and audit evidence; blocking them would make this guardrail non-adoptable.
+const SCAN_DIRS = [
+    'catalog',
+    'commands',
+    'scripts',
+    'test-fixtures',
+    'blueprints/planned',
+    'blueprints/in-progress',
+];
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.agent', '.omx', '.codex']);
+const TEXT_EXTENSIONS = new Set([
+    '.md',
+    '.mdx',
+    '.txt',
+    '.json',
+    '.yaml',
+    '.yml',
+    '.ts',
+    '.tsx',
+    '.js',
+    '.jsx',
+    '.sh',
+]);
+export function auditNoLegacyCliBin(rootDirectory = process.cwd()) {
+    const root = resolve(rootDirectory);
+    const violations = [];
+    let checked = 0;
+    for (const dir of SCAN_DIRS) {
+        const absoluteDir = join(root, dir);
+        if (!existsSync(absoluteDir))
+            continue;
+        for (const absolutePath of walkTextFiles(absoluteDir)) {
+            checked += 1;
+            const relativePath = relative(root, absolutePath);
+            const content = readFileSync(absolutePath, 'utf8');
+            const lines = content.split('\n');
+            for (const [index, line] of lines.entries()) {
+                const matches = line.matchAll(LEGACY_COMMAND_PATTERN);
+                for (const match of matches) {
+                    const snippet = match[0]?.trim();
+                    if (!snippet)
+                        continue;
+                    if (isAllowedLegacyLine(line))
+                        continue;
+                    violations.push({
+                        file: relativePath,
+                        message: `Line ${index + 1} exposes legacy command ${JSON.stringify(snippet)} without current-state/migration context and an exact \`webpresso agent ...\` replacement.`,
+                    });
+                }
+            }
+        }
+    }
+    return {
+        ok: violations.length === 0,
+        title: 'No retired CLI aliases in active docs/scripts',
+        checked,
+        violations,
+    };
+}
+function walkTextFiles(directory) {
+    const entries = readdirSync(directory, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        if (SKIP_DIRS.has(entry.name))
+            continue;
+        const absolutePath = join(directory, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...walkTextFiles(absolutePath));
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        const extension = entry.name.includes('.') ? `.${entry.name.split('.').pop()}` : '';
+        if (TEXT_EXTENSIONS.has(extension))
+            files.push(absolutePath);
+    }
+    return files;
+}
+function isAllowedLegacyLine(line) {
+    LEGACY_COMMAND_PATTERN.lastIndex = 0;
+    if (!LEGACY_COMMAND_PATTERN.test(line))
+        return true;
+    LEGACY_COMMAND_PATTERN.lastIndex = 0;
+    if (INTERNAL_HELPER_PATTERN.test(line))
+        return true;
+    if (!MIGRATION_MARKER_PATTERN.test(line))
+        return false;
+    return REPLACEMENT_PATTERN.test(line);
+}
+//# sourceMappingURL=no-legacy-cli-bin.js.map

package/dist/esm/audit/package-surface.js

@@ -47,6 +47,7 @@ const SKIP_DIRECTORIES = new Set([
     '.omx',
     '.omc',
     '.stryker-tmp',
+    '.webpresso-packed-surface',
     'node_modules',
     'dist',
     'build',
@@ -393,6 +394,7 @@ function stagePackedFiles(root, destinationRoot, candidate, packedFiles) {
 function runSecretlint(stageRoot, packageRoot) {
     const rcPath = findSecretlintRc(packageRoot);
     const outputFile = join(stageRoot, '.secretlint-output.json');
+    const toolRoot = findSecretlintToolRoot(packageRoot) ?? findSecretlintToolRoot(process.cwd());
     const args = ['exec', 'secretlint', '--format', 'json', '--output', outputFile, '--no-gitignore'];
     if (rcPath) {
         args.push('--secretlintrc', rcPath);
@@ -403,7 +405,7 @@ function runSecretlint(stageRoot, packageRoot) {
     args.push(join(stageRoot, '**/*'));
     try {
         execFileSync('pnpm', args, {
-            cwd: packageRoot,
+            cwd: toolRoot ?? packageRoot,
             encoding: 'utf8',
             stdio: ['ignore', 'pipe', 'pipe'],
             maxBuffer: 20 * 1024 * 1024,
@@ -421,6 +423,17 @@ function runSecretlint(stageRoot, packageRoot) {
         rmSync(outputFile, { force: true });
     }
 }
+function findSecretlintToolRoot(start) {
+    let current = resolve(start);
+    while (true) {
+        if (existsSync(join(current, 'node_modules', '.bin', 'secretlint')))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
 function findSecretlintRc(root) {
     const candidates = [
         '.secretlintrc.json',

package/dist/esm/audit/repo-guardrails.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { join, relative, resolve, sep } from 'node:path';
 import matter from 'gray-matter';
 import { blueprintDerivedHandoffSchema } from '#execution/types';
+import { BLUEPRINT_OVERVIEW_FILENAME, isBlueprintSupportingMarkdownRelativePath, parseBlueprintDocumentRelativePath, } from '#utils/document-paths.js';
 import { validateLoreTrailers } from './commit-message-lore.js';
 const DEFAULT_COMMIT_TYPES = [
     'feat',
@@ -209,33 +210,59 @@ export function auditBlueprintLifecycle(rootDirectory = process.cwd(), options =
         if (!existsSync(statusRoot))
             continue;
         for (const entry of readdirSync(statusRoot, { withFileTypes: true })) {
-            if (!entry.isDirectory())
+            if (!entry.isDirectory() && !entry.isFile())
                 continue;
-            const overviewPath = join(statusRoot, entry.name, '_overview.md');
-            checked += 1;
-            if (!existsSync(overviewPath)) {
-                violations.push({
-                    file: relativePath(root, overviewPath),
-                    message: 'Missing _overview.md',
-                });
+            const canonicalPath = entry.isDirectory()
+                ? join(statusRoot, entry.name, BLUEPRINT_OVERVIEW_FILENAME)
+                : join(statusRoot, entry.name);
+            const relativeBlueprintPath = relative(blueprintsRoot, canonicalPath);
+            const parsedPath = parseBlueprintDocumentRelativePath(relativeBlueprintPath);
+            if (entry.isDirectory()) {
+                checked += 1;
+                if (!existsSync(canonicalPath)) {
+                    const hasNestedMarkdown = readdirSync(join(statusRoot, entry.name), {
+                        withFileTypes: true,
+                    }).some((nested) => nested.isFile() && nested.name.endsWith('.md') && nested.name !== 'README.md');
+                    if (hasNestedMarkdown) {
+                        violations.push({
+                            file: relativePath(root, canonicalPath),
+                            message: 'Blueprint folders with supporting markdown must include _overview.md',
+                        });
+                    }
+                    else {
+                        violations.push({
+                            file: relativePath(root, canonicalPath),
+                            message: 'Missing _overview.md',
+                        });
+                    }
+                    continue;
+                }
+            }
+            else {
+                if (!parsedPath || isBlueprintSupportingMarkdownRelativePath(relativeBlueprintPath)) {
+                    continue;
+                }
+                checked += 1;
+            }
+            if (!parsedPath) {
                 continue;
             }
-            const raw = readFileSync(overviewPath, 'utf8');
+            const raw = readFileSync(canonicalPath, 'utf8');
             const frontmatter = matter(raw).data;
             if (frontmatter.type !== 'blueprint' && frontmatter.type !== 'parent-roadmap') {
                 violations.push({
-                    file: relativePath(root, overviewPath),
-                    message: 'Blueprint overview must use type: blueprint or parent-roadmap',
+                    file: relativePath(root, canonicalPath),
+                    message: 'Blueprint markdown must use type: blueprint or parent-roadmap',
                 });
             }
             if (frontmatter.status !== status) {
                 violations.push({
-                    file: relativePath(root, overviewPath),
+                    file: relativePath(root, canonicalPath),
                     message: `Blueprint status must match folder (${status})`,
                 });
             }
             violations.push(...validateBlueprintLinkingFrontmatter({
-                file: relativePath(root, overviewPath),
+                file: relativePath(root, canonicalPath),
                 frontmatter,
                 status,
             }));