@webpresso/agent-kit 0.21.5 → 0.24.0

package/dist/esm/e2e/config.js

@@ -1,15 +1,141 @@
 import { z } from 'zod';
 export const WEBPRESSO_CONFIG_FILE_NAME = 'webpresso.config.ts';
 export const WEBPRESSO_CONFIG_EXPORT_NAME = 'webpressoConfig';
+export const AGENT_KIT_CONFIG_FILE_NAME = 'agent-kit.config.ts';
+export const AGENT_KIT_CONFIG_EXPORT_NAME = 'agentKitConfig';
+export const WEBPRESSO_CONFIG_CANDIDATES = [
+    {
+        fileName: AGENT_KIT_CONFIG_FILE_NAME,
+        exportName: AGENT_KIT_CONFIG_EXPORT_NAME,
+    },
+    {
+        fileName: WEBPRESSO_CONFIG_FILE_NAME,
+        exportName: WEBPRESSO_CONFIG_EXPORT_NAME,
+    },
+];
+const wranglerEnvNameSchema = z
+    .string()
+    .min(1, 'wranglerEnvName must not be empty.')
+    .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, 'wranglerEnvName must be dash-safe lowercase letters, numbers, and hyphens only.');
 const e2eWebpressoConfigSchema = z
     .object({
     hostAdapterModule: z.string().min(1, 'e2e.hostAdapterModule must not be empty.'),
     hostAdapterExport: z.string().min(1, 'e2e.hostAdapterExport must not be empty.').optional(),
 })
     .strict();
+const cloudflareDeployLaneSchema = z
+    .object({
+    wranglerEnvName: wranglerEnvNameSchema,
+})
+    .strict();
+const previewPrCloudflareDeployLaneSchema = z
+    .object({
+    wranglerEnvNamePattern: z
+        .string()
+        .min(1, 'wranglerEnvNamePattern must not be empty.')
+        .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*-<n>$/, 'wranglerEnvNamePattern must be dash-safe and end with -<n>.'),
+})
+    .strict();
+const productionCloudflareDeployLaneSchema = cloudflareDeployLaneSchema.extend({
+    wranglerEnvName: wranglerEnvNameSchema.refine((value) => value === 'production', {
+        message: 'deploy.cloudflare.lanes.prd.wranglerEnvName must be "production".',
+    }),
+    deployedWorkerNameMode: z.literal('top_level_name'),
+});
+const cloudflareRouteSpecSchema = z
+    .object({
+    pattern: z.string().min(1, 'routeSpec.pattern must not be empty.'),
+})
+    .strict();
+const cloudflareDurableObjectBindingSchema = z
+    .object({
+    name: z.string().min(1, 'durableObjectBindings[].name must not be empty.'),
+    className: z.string().min(1, 'durableObjectBindings[].className must not be empty.'),
+    scriptName: z.string().min(1, 'durableObjectBindings[].scriptName must not be empty.').optional(),
+})
+    .strict();
+const cloudflareTargetSchema = z
+    .object({
+    id: z.string().min(1, 'deploy.cloudflare.targets[].id must not be empty.'),
+    type: z.enum(['single_worker', 'worker_plus_assets', 'monorepo_multi_target']),
+    topLevelWorkerName: z.string().min(1, 'topLevelWorkerName must not be empty.'),
+    previewTransport: z.enum(['custom_domain_env', 'workers_dev_env']),
+    routeSpec: cloudflareRouteSpecSchema.optional(),
+    durableObjectBindings: z.array(cloudflareDurableObjectBindingSchema).optional(),
+    vars: z.record(z.string(), z.unknown()),
+    requiredSecrets: z.array(z.string().min(1, 'requiredSecrets[] must not be empty.')),
+    storageMode: z.enum(['isolated', 'shared_via_script_name']),
+    destroyMode: z.literal('wrangler_delete_env'),
+    repoCleanupHook: z.string().min(1, 'repoCleanupHook must not be empty.').optional(),
+    blastRadiusDoc: z.string().min(1, 'blastRadiusDoc must not be empty.').optional(),
+    productionStrategyDefault: z.enum(['direct', 'gradual']),
+})
+    .strict()
+    .superRefine((target, ctx) => {
+    const isDurableObjectTarget = (target.durableObjectBindings?.length ?? 0) > 0;
+    if (target.previewTransport === 'custom_domain_env' && !target.routeSpec) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['routeSpec'],
+            message: 'routeSpec is required when previewTransport is "custom_domain_env".',
+        });
+    }
+    if (isDurableObjectTarget && target.previewTransport !== 'custom_domain_env') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['previewTransport'],
+            message: 'Durable Object targets must use previewTransport "custom_domain_env" unless a future explicit exception contract is introduced.',
+        });
+    }
+    if (isDurableObjectTarget && Object.keys(target.vars).length === 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['vars'],
+            message: 'Durable Object targets must declare at least one env-specific var.',
+        });
+    }
+    if (isDurableObjectTarget && target.requiredSecrets.length === 0) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['requiredSecrets'],
+            message: 'Durable Object targets must declare at least one required secret name.',
+        });
+    }
+    if (target.storageMode === 'shared_via_script_name' && !target.blastRadiusDoc) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ['blastRadiusDoc'],
+            message: 'blastRadiusDoc is required when storageMode is "shared_via_script_name".',
+        });
+    }
+});
+const cloudflareDeployConfigSchema = z
+    .object({
+    lanes: z
+        .object({
+        dev: cloudflareDeployLaneSchema,
+        preview_main: cloudflareDeployLaneSchema,
+        preview_pr: previewPrCloudflareDeployLaneSchema,
+        prd: productionCloudflareDeployLaneSchema,
+    })
+        .strict(),
+    production: z
+        .object({
+        metadataPath: z.literal('infra/release-metadata.production.json'),
+    })
+        .strict(),
+    targets: z.array(cloudflareTargetSchema),
+})
+    .strict();
+const deployWebpressoConfigSchema = z
+    .object({
+    cloudflare: cloudflareDeployConfigSchema.optional(),
+})
+    .strict();
 const webpressoConfigSchema = z
     .object({
     e2e: e2eWebpressoConfigSchema.optional(),
+    deploy: deployWebpressoConfigSchema.optional(),
 })
     .strict();
 export class WebpressoConfigValidationError extends Error {

package/dist/esm/e2e/execution.js

@@ -18,6 +18,7 @@ export async function createE2eExecutionPlan(input, cwd = process.cwd()) {
             workers: input.workers,
             testList: input.testList,
             passthrough: input.passthrough,
+            outputPolicy: input.outputPolicy,
             filterOutput: input.filterOutput,
         });
     }
@@ -36,6 +37,7 @@ export async function createE2eExecutionPlan(input, cwd = process.cwd()) {
             workers: input.workers,
             testList: input.testList,
             passthrough: input.passthrough,
+            outputPolicy: input.outputPolicy,
             filterOutput: input.filterOutput,
         });
     }
@@ -51,6 +53,7 @@ export async function createE2eExecutionPlan(input, cwd = process.cwd()) {
             workers: input.workers,
             testList: input.testList,
             passthrough: input.passthrough,
+            outputPolicy: input.outputPolicy,
             filterOutput: input.filterOutput,
         });
     }
@@ -63,6 +66,7 @@ export async function createE2eExecutionPlan(input, cwd = process.cwd()) {
         workers: input.workers,
         testList: input.testList,
         passthrough: input.passthrough,
+        outputPolicy: input.outputPolicy,
         filterOutput: input.filterOutput,
     });
 }

package/dist/esm/e2e/load-host-adapter.d.ts

@@ -19,7 +19,12 @@ export declare class WebpressoConfigLoadError extends Error {
 }
 export declare class WebpressoConfigExportError extends Error {
     readonly configPath: string;
-    constructor(configPath: string);
+    readonly exportName: string;
+    constructor(configPath: string, exportName?: string);
+}
+export declare class WebpressoConfigAmbiguousError extends Error {
+    readonly configPaths: readonly string[];
+    constructor(configPaths: readonly string[]);
 }
 export declare class HostAdapterModuleLoadError extends Error {
     readonly moduleSpecifier: string;

package/dist/esm/e2e/load-host-adapter.js

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import { dirname, resolve, parse } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { WEBPRESSO_CONFIG_EXPORT_NAME, WEBPRESSO_CONFIG_FILE_NAME, validateWebpressoConfig, } from './config.js';
+import { WEBPRESSO_CONFIG_CANDIDATES, WEBPRESSO_CONFIG_EXPORT_NAME, WEBPRESSO_CONFIG_FILE_NAME, validateWebpressoConfig, } from './config.js';
 import { FALLBACK_HOST_ADAPTER_EXPORT_NAMES, isE2eHostAdapter } from './host-adapter.js';
 export class WebpressoConfigLoadError extends Error {
     configPath;
@@ -15,12 +15,22 @@ export class WebpressoConfigLoadError extends Error {
 }
 export class WebpressoConfigExportError extends Error {
     configPath;
-    constructor(configPath) {
-        super(`Expected ${WEBPRESSO_CONFIG_FILE_NAME} at ${configPath} to export ${WEBPRESSO_CONFIG_EXPORT_NAME}.`);
+    exportName;
+    constructor(configPath, exportName = WEBPRESSO_CONFIG_EXPORT_NAME) {
+        super(`Expected config at ${configPath} to export ${exportName}.`);
         this.configPath = configPath;
+        this.exportName = exportName;
         this.name = 'WebpressoConfigExportError';
     }
 }
+export class WebpressoConfigAmbiguousError extends Error {
+    configPaths;
+    constructor(configPaths) {
+        super(`Multiple Webpresso config files found: ${configPaths.join(', ')}`);
+        this.configPaths = configPaths;
+        this.name = 'WebpressoConfigAmbiguousError';
+    }
+}
 export class HostAdapterModuleLoadError extends Error {
     moduleSpecifier;
     configPath;
@@ -55,9 +65,12 @@ export function resolveWebpressoConfigPath(cwd = process.cwd()) {
 }
 export function findWebpressoConfigPath(cwd = process.cwd()) {
     for (const searchDir of getSearchDirectories(cwd)) {
-        const configPath = getWebpressoConfigPath(searchDir);
-        if (existsSync(configPath)) {
-            return configPath;
+        const configPaths = WEBPRESSO_CONFIG_CANDIDATES.map((candidate) => resolve(searchDir, candidate.fileName)).filter((configPath) => existsSync(configPath));
+        if (configPaths.length > 1) {
+            throw new WebpressoConfigAmbiguousError(configPaths);
+        }
+        if (configPaths.length === 1) {
+            return configPaths[0];
         }
     }
     return null;
@@ -67,11 +80,12 @@ export async function loadWebpressoConfig(options = {}) {
     const configModule = await loadModuleNamespace(pathToFileURL(configPath).href, (cause) => {
         throw new WebpressoConfigLoadError(configPath, cause);
     });
-    if (!(WEBPRESSO_CONFIG_EXPORT_NAME in configModule)) {
-        throw new WebpressoConfigExportError(configPath);
+    const exportName = expectedConfigExportName(configPath);
+    if (!(exportName in configModule)) {
+        throw new WebpressoConfigExportError(configPath, exportName);
     }
     return {
-        config: validateWebpressoConfig(configModule[WEBPRESSO_CONFIG_EXPORT_NAME], configPath),
+        config: validateWebpressoConfig(configModule[exportName], configPath),
         configPath,
     };
 }
@@ -138,6 +152,10 @@ function resolveModuleSpecifier(moduleSpecifier, configPath) {
     }
     return moduleSpecifier;
 }
+function expectedConfigExportName(configPath) {
+    const candidate = WEBPRESSO_CONFIG_CANDIDATES.find((item) => configPath.endsWith(item.fileName));
+    return candidate?.exportName ?? WEBPRESSO_CONFIG_EXPORT_NAME;
+}
 async function loadModuleNamespace(moduleSpecifier, onError) {
     try {
         const moduleNamespace = await import(moduleSpecifier);

package/dist/esm/e2e/run-planner.js

@@ -76,6 +76,7 @@ function planE2eRunsFromSuites(options) {
                 workers: options.request.workers,
                 testList: options.request.testList,
                 passthrough: options.request.passthrough,
+                outputPolicy: options.request.outputPolicy,
                 filterOutput: options.request.filterOutput,
             });
             runs.push({

package/dist/esm/e2e/types.d.ts

@@ -1,3 +1,4 @@
+import type { ManagedRunnerOutputPolicy } from '#tool-runtime';
 export type E2eRunnerKind = 'playwright' | 'vitest' | 'command';
 export interface CommandConfig {
     command: string;
@@ -49,6 +50,7 @@ export interface E2eCommandRequest {
     testList?: string;
     passthrough?: readonly string[];
     filterOutput?: boolean;
+    outputPolicy?: ManagedRunnerOutputPolicy;
 }
 export interface E2eExecutionRequest extends E2eCommandRequest {
     suite?: string;

package/dist/esm/format/index.js

@@ -35,9 +35,7 @@ export async function runFormat(options = {}) {
     if (options.files && options.files.length > 0)
         args.push(...options.files);
     const resolution = getManagedRunner('oxfmt', {
-        fallbackCommand: 'oxfmt',
-        fallbackArgs: [],
-        filterOutput: false,
+        outputPolicy: 'structured',
     });
     const outcome = await runCommand(resolution.command, [...resolution.args, ...args], runOptions);
     if (isRunFailure(outcome)) {

package/dist/esm/hooks/guard-switch/index.d.ts

@@ -1,3 +1,3 @@
 #!/usr/bin/env bun
-export {};
+export declare function main(): Promise<void>;
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/hooks/guard-switch/index.js

@@ -1,18 +1,26 @@
 #!/usr/bin/env bun
 import { runHook } from '#hooks/shared/hook-bootstrap';
+import { realpathSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 import { setGuardEnabled } from './state.js';
-runHook((input) => {
-    const normalized = (input.prompt ?? '').toLowerCase().trim();
-    if (normalized === 'guard off') {
-        setGuardEnabled(false);
-        console.error('🛡️ Guard disabled — pretool validators will be skipped');
-        process.exit(2);
-    }
-    if (normalized === 'guard on') {
-        setGuardEnabled(true);
-        console.error('🛡️ Guard enabled — pretool validators active');
-        process.exit(2);
-    }
-    return null;
-}, () => '{}');
+export async function main() {
+    runHook((input) => {
+        const normalized = (input.prompt ?? '').toLowerCase().trim();
+        if (normalized === 'guard off') {
+            setGuardEnabled(false);
+            console.error('🛡️ Guard disabled — pretool validators will be skipped');
+            process.exit(2);
+        }
+        if (normalized === 'guard on') {
+            setGuardEnabled(true);
+            console.error('🛡️ Guard enabled — pretool validators active');
+            process.exit(2);
+        }
+        return null;
+    }, () => '{}');
+}
+if (process.argv[1] &&
+    realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1])) {
+    void main();
+}
 //# sourceMappingURL=index.js.map

package/dist/esm/hooks/post-tool/lint-after-edit.d.ts

@@ -14,4 +14,5 @@ export declare function shouldLintFile(input: ToolInput): boolean;
  */
 export declare function lintFile(filePath: string, _projectDir: string): boolean;
 export declare function processPostToolUse(input: ToolInput, projectDir: string): boolean;
+export declare function main(): Promise<void>;
 //# sourceMappingURL=lint-after-edit.d.ts.map

package/dist/esm/hooks/post-tool/lint-after-edit.js

@@ -46,12 +46,15 @@ export function processPostToolUse(input, projectDir) {
     const filePath = input.tool_input.file_path;
     return lintFile(filePath, projectDir);
 }
-if (process.argv[1] &&
-    realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1])) {
+export async function main() {
     runHook((input) => {
         const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
         processPostToolUse(input, projectDir);
         return null;
     }, () => '{}');
 }
+if (process.argv[1] &&
+    realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1])) {
+    void main();
+}
 //# sourceMappingURL=lint-after-edit.js.map

package/dist/esm/hooks/pretool-guard/validators/file-conventions.js

@@ -46,7 +46,7 @@ export function validateFileConventions(input) {
     if (nonCanonicalPlanningViolation) {
         return { validator: 'file-conventions', passed: false, message: nonCanonicalPlanningViolation };
     }
-    const blueprintPathViolation = getBlueprintPathViolation(normalized);
+    const blueprintPathViolation = getBlueprintPathViolation(normalized, undefined, input.cwd);
     if (blueprintPathViolation) {
         return { validator: 'file-conventions', passed: false, message: blueprintPathViolation };
     }

package/dist/esm/hooks/pretool-guard/validators/forbidden-commands.d.ts

@@ -29,6 +29,11 @@ interface BlockedScriptSpec {
     category: CommandCategory;
     suggestion: string;
 }
+interface BlockedRawNodeModulesToolSpec {
+    modulePath: string;
+    category: CommandCategory;
+    suggestion: string;
+}
 interface RedirectOptions {
     mcpReady?: boolean;
     mcp?: MCPRedirectConfig;
@@ -39,6 +44,7 @@ export declare const AUDIT_MODE_ENV = "FORBIDDEN_COMMANDS_AUDIT";
 export declare const DOCS_REF = "AGENTS.md \"Forbidden Commands (CRITICAL)\" section";
 export declare const BLOCKED_TOOLS: BlockedToolSpec[];
 export declare const BLOCKED_SCRIPTS: BlockedScriptSpec[];
+export declare const BLOCKED_RAW_NODE_MODULE_TOOLS: BlockedRawNodeModulesToolSpec[];
 export declare function generateRules(): CommandRule[];
 export declare const COMMAND_RULES: CommandRule[];
 export declare const SUGGESTION_MODIFIERS: SuggestionModifier[];

package/dist/esm/hooks/pretool-guard/validators/forbidden-commands.js

@@ -19,8 +19,18 @@ const TYPECHECK_HINT = 'wp_typecheck MCP tool with package/file scope';
 const E2E_HINT = 'wp_e2e MCP tool';
 const ENV_HINT = 'Use the repo-approved environment wrapper for secret-bearing commands';
 const TASK_TARGET_HINT = 'Use the repo-approved vp facade or MCP tool instead of raw execution';
-const EXEC_RUNNERS = ['vp exec'];
-const DIRECT_RUNNERS = ['vp'];
+const EXEC_RUNNERS = [
+    'vp exec',
+    'pnpm exec',
+    'npm exec',
+    'npm exec --',
+    'npx',
+    'pnpx',
+    'yarn exec',
+    'yarn dlx',
+    'bunx',
+];
+const DIRECT_RUNNERS = ['vp', 'pnpm', 'yarn', 'yarnpkg'];
 const SCRIPT_RUNNERS = ['vp run', 'vp', 'pnpm', 'pnpm run', 'just'];
 export const BLOCKED_TOOLS = [
     {
@@ -59,6 +69,11 @@ export const BLOCKED_SCRIPTS = [
     { script: 'e2e', category: 'e2e', suggestion: E2E_HINT },
     { script: 'qa', category: 'unknown', suggestion: QA_HINT },
 ];
+export const BLOCKED_RAW_NODE_MODULE_TOOLS = [
+    { modulePath: 'vitest/vitest.mjs', category: 'test', suggestion: TEST_HINT },
+    { modulePath: 'typescript/bin/tsc', category: 'typecheck', suggestion: TYPECHECK_HINT },
+    { modulePath: 'oxlint/bin/oxlint', category: 'lint', suggestion: LINT_HINT },
+];
 function escapeRegex(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -66,6 +81,9 @@ function buildToolPattern(prefix, tool) {
     const escaped = prefix ? `${escapeRegex(prefix)} ${escapeRegex(tool)}` : escapeRegex(tool);
     return new RegExp(`^${escaped}(\\s|$)`);
 }
+function buildRawNodeModulesToolPattern(modulePath) {
+    return new RegExp(`^node\\s+(?:\\.\\/)?node_modules\\/${escapeRegex(modulePath)}(?:\\s|$)`);
+}
 export function generateRules() {
     const rules = [];
     for (const spec of BLOCKED_TOOLS) {
@@ -104,6 +122,13 @@ export function generateRules() {
             });
         }
     }
+    for (const spec of BLOCKED_RAW_NODE_MODULE_TOOLS) {
+        rules.push({
+            pattern: buildRawNodeModulesToolPattern(spec.modulePath),
+            category: spec.category,
+            suggestion: spec.suggestion,
+        });
+    }
     rules.push({
         pattern: /^vp exec markdownlint-cli2\b/,
         category: 'unknown',

package/dist/esm/hooks/pretool-guard/validators/path-contract.d.ts

@@ -11,5 +11,6 @@ export declare function getNonCanonicalPlanningPathViolation(filePath: string, b
  * accepted blueprints root layout (or the explicitly provided root).
  */
 export declare function isCanonicalBlueprintOverviewPath(filePath: string, blueprintsRoot?: string): boolean;
-export declare function getBlueprintPathViolation(filePath: string, blueprintsRoot?: string): string | null;
+export declare function isCanonicalBlueprintDocumentPath(filePath: string, blueprintsRoot?: string): boolean;
+export declare function getBlueprintPathViolation(filePath: string, blueprintsRoot?: string, cwd?: string): string | null;
 //# sourceMappingURL=path-contract.d.ts.map

package/dist/esm/hooks/pretool-guard/validators/path-contract.js

@@ -1,16 +1,10 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { BLUEPRINT_OVERVIEW_FILENAME, getBlueprintAlternateDocumentPath, isBlueprintSupportingMarkdownRelativePath, isBlueprintStatus, parseBlueprintDocumentRelativePath, } from '#utils/document-paths.js';
 export const BLUEPRINTS_ROOT = 'webpresso/blueprints';
 const DEFAULT_BLUEPRINTS_ROOT = 'blueprints';
 export const TECH_DEBT_ROOT = 'webpresso/tech-debt';
 const DEFAULT_TECH_DEBT_ROOT = 'tech-debt';
-const BLUEPRINT_STATUSES = new Set([
-    'draft',
-    'planned',
-    'parked',
-    'in-progress',
-    'completed',
-    'archived',
-]);
-const KEBAB_CASE_SEGMENT = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 // Both canonical blueprint-root layouts accepted by default.
 const CANONICAL_BLUEPRINTS_ROOTS = [BLUEPRINTS_ROOT, DEFAULT_BLUEPRINTS_ROOT];
 const CANONICAL_TECH_DEBT_ROOTS = [TECH_DEBT_ROOT, DEFAULT_TECH_DEBT_ROOT];
@@ -20,6 +14,16 @@ function normalizePlanningPath(filePath) {
 function matchesRoot(normalized, root) {
     return normalized === root || normalized.startsWith(`${root}/`);
 }
+function stripBlueprintRoot(normalized, roots) {
+    for (const root of roots) {
+        if (normalized === root)
+            return { relativePath: '', root };
+        if (normalized.startsWith(`${root}/`)) {
+            return { relativePath: normalized.slice(root.length + 1), root };
+        }
+    }
+    return null;
+}
 /**
  * Returns true if the path is under any accepted blueprints root.
  * Pass `blueprintsRoot` to restrict to a single configured root.
@@ -66,39 +70,60 @@ export function getNonCanonicalPlanningPathViolation(filePath, blueprintsRoot, t
  * accepted blueprints root layout (or the explicitly provided root).
  */
 export function isCanonicalBlueprintOverviewPath(filePath, blueprintsRoot) {
+    const parsed = getCanonicalBlueprintDocument(filePath, blueprintsRoot);
+    return parsed?.shape === 'folder';
+}
+export function isCanonicalBlueprintDocumentPath(filePath, blueprintsRoot) {
+    return getCanonicalBlueprintDocument(filePath, blueprintsRoot) !== null;
+}
+function getCanonicalBlueprintDocument(filePath, blueprintsRoot) {
     const normalized = normalizePlanningPath(filePath);
     const roots = blueprintsRoot ? [blueprintsRoot] : CANONICAL_BLUEPRINTS_ROOTS;
-    return roots.some((root) => {
-        const rootParts = root.split('/');
-        const parts = normalized.split('/');
-        const n = rootParts.length;
-        return (parts.length === n + 3 &&
-            parts.slice(0, n).join('/') === root &&
-            BLUEPRINT_STATUSES.has(parts[n] ?? '') &&
-            KEBAB_CASE_SEGMENT.test(parts[n + 1] ?? '') &&
-            parts[n + 2] === '_overview.md');
-    });
+    const stripped = stripBlueprintRoot(normalized, roots);
+    return stripped ? parseBlueprintDocumentRelativePath(stripped.relativePath) : null;
 }
-export function getBlueprintPathViolation(filePath, blueprintsRoot) {
+export function getBlueprintPathViolation(filePath, blueprintsRoot, cwd = process.cwd()) {
     const normalized = normalizePlanningPath(filePath);
     if (!isBlueprintPath(normalized, blueprintsRoot))
         return null;
-    if (normalized.endsWith('/_overview.md') &&
-        !isCanonicalBlueprintOverviewPath(normalized, blueprintsRoot)) {
-        const root = blueprintsRoot ?? BLUEPRINTS_ROOT;
-        return `Blueprint overview files must live at ${root}/<status>/<slug>/_overview.md. Got: ${normalized}`;
-    }
     const roots = blueprintsRoot ? [blueprintsRoot] : CANONICAL_BLUEPRINTS_ROOTS;
-    for (const root of roots) {
-        const rootParts = root.split('/');
-        const parts = normalized.split('/');
-        const n = rootParts.length;
-        if (parts.length === n + 2 &&
-            parts.slice(0, n).join('/') === root &&
-            BLUEPRINT_STATUSES.has(parts[n] ?? '') &&
-            normalized.endsWith('.md')) {
-            return `Blueprint markdown files cannot live directly under a status directory. Move this file to ${root}/${parts[n]}/<slug>/_overview.md or place supporting docs inside ${root}/${parts[n]}/<slug>/. Got: ${normalized}`;
+    const stripped = stripBlueprintRoot(normalized, roots);
+    if (!stripped) {
+        return null;
+    }
+    const parsed = parseBlueprintDocumentRelativePath(stripped.relativePath);
+    if (parsed) {
+        const blueprintRoot = path.isAbsolute(filePath)
+            ? path.join(path.parse(filePath).root, stripped.root)
+            : path.join(cwd, stripped.root);
+        const currentPath = path.isAbsolute(filePath) ? filePath : path.join(cwd, normalized);
+        const alternate = getBlueprintAlternateDocumentPath(blueprintRoot, currentPath);
+        if (alternate && existsSync(alternate)) {
+            return `Blueprint slug "${parsed.state}/${parsed.slug}" cannot exist in both flat and folder forms. Remove either ${path.relative(cwd, filePath).replace(/\\/g, '/')} or ${path.relative(cwd, alternate).replace(/\\/g, '/')}.`;
         }
+        return null;
+    }
+    const parts = stripped.relativePath.split('/').filter((segment) => segment.length > 0);
+    const [state, slug, doc] = parts;
+    const root = stripped.root;
+    if (parts.length === 2 &&
+        typeof doc === 'undefined' &&
+        typeof slug === 'string' &&
+        slug.endsWith('.md')) {
+        return `Blueprint markdown under ${root}/<status>/ must be either <slug>.md or <slug>/${BLUEPRINT_OVERVIEW_FILENAME}. Got: ${normalized}`;
+    }
+    if (parts.length === 3 && doc === BLUEPRINT_OVERVIEW_FILENAME) {
+        return `Blueprint overview files must live at ${root}/<status>/<slug>/${BLUEPRINT_OVERVIEW_FILENAME}. Got: ${normalized}`;
+    }
+    if (parts.length === 3 && isBlueprintSupportingMarkdownRelativePath(stripped.relativePath)) {
+        const canonicalOverviewPath = path.join(cwd, root, state ?? '', slug ?? '', BLUEPRINT_OVERVIEW_FILENAME);
+        if (!existsSync(canonicalOverviewPath)) {
+            return `Supporting blueprint markdown requires ${root}/${state}/${slug}/${BLUEPRINT_OVERVIEW_FILENAME}. Got: ${normalized}`;
+        }
+        return null;
+    }
+    if (parts.length >= 3 && isBlueprintStatus(state)) {
+        return `Blueprint markdown must use one of ${root}/<status>/<slug>.md or ${root}/<status>/<slug>/${BLUEPRINT_OVERVIEW_FILENAME}. Supporting markdown is only allowed beside ${BLUEPRINT_OVERVIEW_FILENAME}. Got: ${normalized}`;
     }
     return null;
 }

package/dist/esm/hooks/pretool-guard/validators/plan-frontmatter.js

@@ -1,6 +1,6 @@
 import jsYaml from 'js-yaml';
 import { getContent, getFilePath } from '#hooks/shared/types';
-import { getNonCanonicalPlanningPathViolation, isBlueprintPath } from './path-contract.js';
+import { getNonCanonicalPlanningPathViolation, isBlueprintPath, isCanonicalBlueprintDocumentPath, } from './path-contract.js';
 import { createSkipResult } from './skip-result.js';
 // Keep aligned with webpresso/blueprint planStatusSchema + plan type enum.
 const VALID_TYPES = ['blueprint', 'parent-roadmap'];
@@ -10,8 +10,8 @@ function shouldValidatePath(filePath) {
     const normalized = filePath.startsWith('/') ? filePath.slice(1) : filePath;
     const nonCanonicalPlanningPath = getNonCanonicalPlanningPathViolation(normalized);
     const currentPath = isBlueprintPath(normalized);
-    const isOverviewFile = normalized.endsWith('/README.md') || normalized.endsWith('/_overview.md');
-    return !nonCanonicalPlanningPath && currentPath && isOverviewFile;
+    const isCanonicalBlueprintDoc = isCanonicalBlueprintDocumentPath(normalized);
+    return !nonCanonicalPlanningPath && currentPath && isCanonicalBlueprintDoc;
 }
 export function extractFrontmatterBlock(content) {
     const match = content.match(/^---\n([\s\S]*?)\n---/);