@codedrifters/configulator 0.0.238 → 0.0.240

package/lib/index.d.mts

@@ -2721,6 +2721,77 @@ declare class AwsDeployWorkflow extends Component {
     preSynthesize(): void;
 }
 
+/**
+ * Canonical top-level folders for a configulator monorepo (ADR-006).
+ *
+ * Every sub-project must live under one of these roots. `DOCS` is a
+ * singleton (the single Starlight site at `/docs`); `APPS`, `PACKAGES`,
+ * and `SITES` are parents for `@scope/<name>` sub-projects.
+ *
+ * @see docs/requirements/architectural-decisions/ADR-006-monorepo-layout.md
+ */
+declare const MONOREPO_LAYOUT: {
+    readonly DOCS: "docs";
+    readonly APPS: "apps";
+    readonly PACKAGES: "packages";
+    readonly SITES: "sites";
+};
+type MonorepoLayoutRoot = (typeof MONOREPO_LAYOUT)[keyof typeof MONOREPO_LAYOUT];
+/**
+ * How `MonorepoProject` reacts when a sub-project's `outdir` falls outside
+ * the root expected for its project type (see ADR-006 §4).
+ *
+ * - `"off"` — no validation runs.
+ * - `"warn"` — log a console warning per offending sub-project; synth proceeds.
+ * - `"error"` — throw on the first offending sub-project; synth fails.
+ */
+declare const LAYOUT_ENFORCEMENT: {
+    readonly OFF: "off";
+    readonly WARN: "warn";
+    readonly ERROR: "error";
+};
+type LayoutEnforcement = (typeof LAYOUT_ENFORCEMENT)[keyof typeof LAYOUT_ENFORCEMENT];
+/**
+ * Mapping from configulator project-type class name to the root folder its
+ * `outdir` must live under.
+ *
+ * We key by class name (not class reference) so this module stays free of
+ * import cycles with the project-type files that validate against it.
+ * `StarlightProject` maps to `DOCS` because the docs-singleton rule says
+ * Starlight is only ever used as the monorepo-wide docs site.
+ *
+ * @see ADR-006 §4 — Configulator project-type → `outdir` mapping
+ */
+declare const LAYOUT_ROOT_BY_PROJECT_TYPE: Readonly<Record<string, MonorepoLayoutRoot>>;
+/**
+ * A single offender reported by {@link validateMonorepoLayout}. One entry
+ * per sub-project whose `outdir` falls outside its expected root.
+ */
+interface LayoutViolation {
+    readonly projectName: string;
+    readonly projectType: string;
+    readonly outdir: string;
+    readonly expectedRoot: MonorepoLayoutRoot;
+}
+/**
+ * Inspect every sub-project of `root` and collect those whose `outdir` does
+ * not live under the root expected for their project class (ADR-006 §4).
+ *
+ * - Sub-projects whose class name is not in
+ *   {@link LAYOUT_ROOT_BY_PROJECT_TYPE} are skipped — the contract only
+ *   covers the four documented project types.
+ * - The root project itself is skipped (it *is* the monorepo root, not a
+ *   sub-project).
+ * - `outdir` comparison is done in POSIX form against the project root so
+ *   absolute paths synthesised on Windows still match.
+ */
+declare function validateMonorepoLayout(root: Project$1): Array<LayoutViolation>;
+/**
+ * Render one {@link LayoutViolation} as an actionable, single-line error
+ * message pointing the reader at ADR-006.
+ */
+declare function formatLayoutViolation(violation: LayoutViolation): string;
+
 /**
  * Each of the below options corresponds to a task property found here:
  *  * https://turborepo.com/docs/reference/configuration#defining-tasks
@@ -3303,6 +3374,22 @@ interface MonorepoProjectOptions extends Omit<TypeScriptProjectOptions$1, "defau
      * @default true
      */
     readonly syncLabels?: SyncLabelsOptions | boolean;
+    /**
+     * How to react when a sub-project's `outdir` falls outside the root
+     * expected for its project type (ADR-006 §4).
+     *
+     * - `"off"` — skip validation entirely.
+     * - `"warn"` — log a console warning per violation; synth proceeds.
+     * - `"error"` — throw on the first violation; synth fails.
+     *
+     * Defaults to `"warn"` during the ADR-006 rollout so existing consumers
+     * with legacy outdirs see actionable warnings but do not break. A future
+     * release will flip the default to `"error"`.
+     *
+     * @default "warn"
+     * @see docs/requirements/architectural-decisions/ADR-006-monorepo-layout.md
+     */
+    readonly layoutEnforcement?: LayoutEnforcement;
 }
 declare class MonorepoProject extends TypeScriptAppProject {
     /**
@@ -3313,7 +3400,22 @@ declare class MonorepoProject extends TypeScriptAppProject {
      * Whether this monorepo consumes configulator from a registry (drives upgrade workflow steps).
      */
     readonly configulatorRegistryConsumer: boolean;
+    /**
+     * Layout-enforcement mode for sub-project `outdir` validation (ADR-006).
+     */
+    readonly layoutEnforcement: LayoutEnforcement;
     constructor(userOptions: MonorepoProjectOptions);
+    /**
+     * Validate sub-project `outdir` values against the ADR-006 monorepo
+     * layout contract. Runs in `preSynthesize` so all sub-projects are
+     * attached by the time we inspect the tree.
+     *
+     * Behavior is controlled by `layoutEnforcement`:
+     * - `"off"`  — skip validation.
+     * - `"warn"` — log a `console.warn` per violation; continue.
+     * - `"error"` — throw on the first violation.
+     */
+    preSynthesize(): void;
     /**
      * Allows a sub project to request installation of dependency at the Monorepo root
      * They must provide a function that is executed after dependencies have been installed
@@ -3636,4 +3738,4 @@ declare const COMPLETE_JOB_ID = "complete";
  */
 declare function addBuildCompleteJob(buildWorkflow: BuildWorkflow): void;
 
-export { AGENT_MODEL, AGENT_PLATFORM, AGENT_RULE_SCOPE, AgentConfig, type AgentConfigOptions, type AgentModel, type AgentPlatform, type AgentPlatformOverrides, type AgentProcedure, type AgentRule, type AgentRuleBundle, type AgentRuleScope, type AgentSkill, type AgentSubAgent, type AgentSubAgentPlatformOverrides, type ApproveMergeUpgradeOptions, AstroConfig, type AstroConfigOptions, type AstroIntegrationSpec, AstroOutput, AstroProject, type AstroProjectOptions, type AwsAccount, AwsCdkProject, type AwsCdkProjectOptions, AwsDeployWorkflow, AwsDeploymentConfig, AwsDeploymentTarget, type AwsDeploymentTargetOptions, type AwsLocalDeploymentConfig, type AwsOrganization, type AwsRegion, AwsTeardownWorkflow, type AwsTeardownWorkflowOptions, BUILT_IN_BUNDLES, CLAUDE_RULE_TARGET, COMPLETE_JOB_ID, type CiDeploymentConfig, type ClassTypeOptions, type ClaudeAutoModeConfig, type ClaudeHookAction, type ClaudeHookEntry, type ClaudeHooksConfig, type ClaudePermissionsConfig, type ClaudeRuleTarget, type ClaudeSandboxConfig, type ClaudeSettingsConfig, type CopilotHandoff, type CursorHookAction, type CursorHooksConfig, type CursorSettingsConfig, DEFAULT_PRIORITY_LABELS, DEFAULT_STATUS_LABELS, DEFAULT_TEARDOWN_BRANCH_PATTERNS, DEFAULT_TYPE_LABELS, type DeployWorkflowOptions, type DeploymentMetadata, type GitBranch, type GitHubBoardMetadata, type GitHubProjectMetadata, type GitHubSprintMetadata, type IDependencyResolver, JsiiFaker, type LabelDefinition, MCP_TRANSPORT, MERGE_METHODS, MIMIMUM_RELEASE_AGE, MINIMUM_RELEASE_AGE, type McpServerConfig, type McpTransport, type MergeMethod, MonorepoProject, type MonorepoProjectOptions, type OrganizationMetadata, PROD_DEPLOY_NAME, PnpmWorkspace, type PnpmWorkspaceOptions, ProjectMetadata, type ProjectMetadataOptions, REQUIREMENTS_WRITER_PATHS, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, type RemoteCacheOptions, type RepositoryMetadata, ResetTask, type ResetTaskOptions, type ResolvedProjectMetadata, type SlackMetadata, type StarlightEditLink, type StarlightLogo, StarlightProject, type StarlightProjectOptions, type StarlightSidebarItem, type StarlightSocialLink, type SyncLabelsOptions, type TemplateResolveResult, TestRunner, TurboRepo, type TurboRepoOptions, TurboRepoTask, type TurboRepoTaskOptions, TypeScriptConfig, TypeScriptProject, type TypeScriptProjectOptions, VERSION, VERSION_KEYS_SKIP, VERSION_NPM_PACKAGES, VSCodeConfig, type VersionKey, Vitest, type VitestConfigOptions, type VitestOptions, addApproveMergeUpgradeWorkflow, addBuildCompleteJob, addSyncLabelsWorkflow, awsCdkBundle, baseBundle, bcmWriterBundle, companyProfileBundle, getLatestEligibleVersion, githubWorkflowBundle, industryDiscoveryBundle, jestBundle, maintenanceAuditBundle, meetingAnalysisBundle, orchestratorBundle, peopleProfileBundle, pnpmBundle, prReviewBundle, projenBundle, requirementsAnalystBundle, requirementsReviewerBundle, requirementsWriterBundle, researchPipelineBundle, resolveModelAlias, resolveTemplateVariables, slackBundle, softwareProfileBundle, turborepoBundle, typescriptBundle, vitestBundle };
+export { AGENT_MODEL, AGENT_PLATFORM, AGENT_RULE_SCOPE, AgentConfig, type AgentConfigOptions, type AgentModel, type AgentPlatform, type AgentPlatformOverrides, type AgentProcedure, type AgentRule, type AgentRuleBundle, type AgentRuleScope, type AgentSkill, type AgentSubAgent, type AgentSubAgentPlatformOverrides, type ApproveMergeUpgradeOptions, AstroConfig, type AstroConfigOptions, type AstroIntegrationSpec, AstroOutput, AstroProject, type AstroProjectOptions, type AwsAccount, AwsCdkProject, type AwsCdkProjectOptions, AwsDeployWorkflow, AwsDeploymentConfig, AwsDeploymentTarget, type AwsDeploymentTargetOptions, type AwsLocalDeploymentConfig, type AwsOrganization, type AwsRegion, AwsTeardownWorkflow, type AwsTeardownWorkflowOptions, BUILT_IN_BUNDLES, CLAUDE_RULE_TARGET, COMPLETE_JOB_ID, type CiDeploymentConfig, type ClassTypeOptions, type ClaudeAutoModeConfig, type ClaudeHookAction, type ClaudeHookEntry, type ClaudeHooksConfig, type ClaudePermissionsConfig, type ClaudeRuleTarget, type ClaudeSandboxConfig, type ClaudeSettingsConfig, type CopilotHandoff, type CursorHookAction, type CursorHooksConfig, type CursorSettingsConfig, DEFAULT_PRIORITY_LABELS, DEFAULT_STATUS_LABELS, DEFAULT_TEARDOWN_BRANCH_PATTERNS, DEFAULT_TYPE_LABELS, type DeployWorkflowOptions, type DeploymentMetadata, type GitBranch, type GitHubBoardMetadata, type GitHubProjectMetadata, type GitHubSprintMetadata, type IDependencyResolver, JsiiFaker, LAYOUT_ENFORCEMENT, LAYOUT_ROOT_BY_PROJECT_TYPE, type LabelDefinition, type LayoutEnforcement, type LayoutViolation, MCP_TRANSPORT, MERGE_METHODS, MIMIMUM_RELEASE_AGE, MINIMUM_RELEASE_AGE, MONOREPO_LAYOUT, type McpServerConfig, type McpTransport, type MergeMethod, type MonorepoLayoutRoot, MonorepoProject, type MonorepoProjectOptions, type OrganizationMetadata, PROD_DEPLOY_NAME, PnpmWorkspace, type PnpmWorkspaceOptions, ProjectMetadata, type ProjectMetadataOptions, REQUIREMENTS_WRITER_PATHS, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, type RemoteCacheOptions, type RepositoryMetadata, ResetTask, type ResetTaskOptions, type ResolvedProjectMetadata, type SlackMetadata, type StarlightEditLink, type StarlightLogo, StarlightProject, type StarlightProjectOptions, type StarlightSidebarItem, type StarlightSocialLink, type SyncLabelsOptions, type TemplateResolveResult, TestRunner, TurboRepo, type TurboRepoOptions, TurboRepoTask, type TurboRepoTaskOptions, TypeScriptConfig, TypeScriptProject, type TypeScriptProjectOptions, VERSION, VERSION_KEYS_SKIP, VERSION_NPM_PACKAGES, VSCodeConfig, type VersionKey, Vitest, type VitestConfigOptions, type VitestOptions, addApproveMergeUpgradeWorkflow, addBuildCompleteJob, addSyncLabelsWorkflow, awsCdkBundle, baseBundle, bcmWriterBundle, companyProfileBundle, formatLayoutViolation, getLatestEligibleVersion, githubWorkflowBundle, industryDiscoveryBundle, jestBundle, maintenanceAuditBundle, meetingAnalysisBundle, orchestratorBundle, peopleProfileBundle, pnpmBundle, prReviewBundle, projenBundle, requirementsAnalystBundle, requirementsReviewerBundle, requirementsWriterBundle, researchPipelineBundle, resolveModelAlias, resolveTemplateVariables, slackBundle, softwareProfileBundle, turborepoBundle, typescriptBundle, validateMonorepoLayout, vitestBundle };

package/lib/index.d.ts

@@ -2770,6 +2770,77 @@ declare class AwsDeployWorkflow extends Component {
     preSynthesize(): void;
 }
 
+/**
+ * Canonical top-level folders for a configulator monorepo (ADR-006).
+ *
+ * Every sub-project must live under one of these roots. `DOCS` is a
+ * singleton (the single Starlight site at `/docs`); `APPS`, `PACKAGES`,
+ * and `SITES` are parents for `@scope/<name>` sub-projects.
+ *
+ * @see docs/requirements/architectural-decisions/ADR-006-monorepo-layout.md
+ */
+declare const MONOREPO_LAYOUT: {
+    readonly DOCS: "docs";
+    readonly APPS: "apps";
+    readonly PACKAGES: "packages";
+    readonly SITES: "sites";
+};
+type MonorepoLayoutRoot = (typeof MONOREPO_LAYOUT)[keyof typeof MONOREPO_LAYOUT];
+/**
+ * How `MonorepoProject` reacts when a sub-project's `outdir` falls outside
+ * the root expected for its project type (see ADR-006 §4).
+ *
+ * - `"off"` — no validation runs.
+ * - `"warn"` — log a console warning per offending sub-project; synth proceeds.
+ * - `"error"` — throw on the first offending sub-project; synth fails.
+ */
+declare const LAYOUT_ENFORCEMENT: {
+    readonly OFF: "off";
+    readonly WARN: "warn";
+    readonly ERROR: "error";
+};
+type LayoutEnforcement = (typeof LAYOUT_ENFORCEMENT)[keyof typeof LAYOUT_ENFORCEMENT];
+/**
+ * Mapping from configulator project-type class name to the root folder its
+ * `outdir` must live under.
+ *
+ * We key by class name (not class reference) so this module stays free of
+ * import cycles with the project-type files that validate against it.
+ * `StarlightProject` maps to `DOCS` because the docs-singleton rule says
+ * Starlight is only ever used as the monorepo-wide docs site.
+ *
+ * @see ADR-006 §4 — Configulator project-type → `outdir` mapping
+ */
+declare const LAYOUT_ROOT_BY_PROJECT_TYPE: Readonly<Record<string, MonorepoLayoutRoot>>;
+/**
+ * A single offender reported by {@link validateMonorepoLayout}. One entry
+ * per sub-project whose `outdir` falls outside its expected root.
+ */
+interface LayoutViolation {
+    readonly projectName: string;
+    readonly projectType: string;
+    readonly outdir: string;
+    readonly expectedRoot: MonorepoLayoutRoot;
+}
+/**
+ * Inspect every sub-project of `root` and collect those whose `outdir` does
+ * not live under the root expected for their project class (ADR-006 §4).
+ *
+ * - Sub-projects whose class name is not in
+ *   {@link LAYOUT_ROOT_BY_PROJECT_TYPE} are skipped — the contract only
+ *   covers the four documented project types.
+ * - The root project itself is skipped (it *is* the monorepo root, not a
+ *   sub-project).
+ * - `outdir` comparison is done in POSIX form against the project root so
+ *   absolute paths synthesised on Windows still match.
+ */
+declare function validateMonorepoLayout(root: Project): Array<LayoutViolation>;
+/**
+ * Render one {@link LayoutViolation} as an actionable, single-line error
+ * message pointing the reader at ADR-006.
+ */
+declare function formatLayoutViolation(violation: LayoutViolation): string;
+
 /**
  * Each of the below options corresponds to a task property found here:
  *  * https://turborepo.com/docs/reference/configuration#defining-tasks
@@ -3352,6 +3423,22 @@ interface MonorepoProjectOptions extends Omit<TypeScriptProjectOptions$1, "defau
      * @default true
      */
     readonly syncLabels?: SyncLabelsOptions | boolean;
+    /**
+     * How to react when a sub-project's `outdir` falls outside the root
+     * expected for its project type (ADR-006 §4).
+     *
+     * - `"off"` — skip validation entirely.
+     * - `"warn"` — log a console warning per violation; synth proceeds.
+     * - `"error"` — throw on the first violation; synth fails.
+     *
+     * Defaults to `"warn"` during the ADR-006 rollout so existing consumers
+     * with legacy outdirs see actionable warnings but do not break. A future
+     * release will flip the default to `"error"`.
+     *
+     * @default "warn"
+     * @see docs/requirements/architectural-decisions/ADR-006-monorepo-layout.md
+     */
+    readonly layoutEnforcement?: LayoutEnforcement;
 }
 declare class MonorepoProject extends TypeScriptAppProject {
     /**
@@ -3362,7 +3449,22 @@ declare class MonorepoProject extends TypeScriptAppProject {
      * Whether this monorepo consumes configulator from a registry (drives upgrade workflow steps).
      */
     readonly configulatorRegistryConsumer: boolean;
+    /**
+     * Layout-enforcement mode for sub-project `outdir` validation (ADR-006).
+     */
+    readonly layoutEnforcement: LayoutEnforcement;
     constructor(userOptions: MonorepoProjectOptions);
+    /**
+     * Validate sub-project `outdir` values against the ADR-006 monorepo
+     * layout contract. Runs in `preSynthesize` so all sub-projects are
+     * attached by the time we inspect the tree.
+     *
+     * Behavior is controlled by `layoutEnforcement`:
+     * - `"off"`  — skip validation.
+     * - `"warn"` — log a `console.warn` per violation; continue.
+     * - `"error"` — throw on the first violation.
+     */
+    preSynthesize(): void;
     /**
      * Allows a sub project to request installation of dependency at the Monorepo root
      * They must provide a function that is executed after dependencies have been installed
@@ -3685,5 +3787,5 @@ declare const COMPLETE_JOB_ID = "complete";
  */
 declare function addBuildCompleteJob(buildWorkflow: BuildWorkflow): void;
 
-export { AGENT_MODEL, AGENT_PLATFORM, AGENT_RULE_SCOPE, AgentConfig, AstroConfig, AstroOutput, AstroProject, AwsCdkProject, AwsDeployWorkflow, AwsDeploymentConfig, AwsDeploymentTarget, AwsTeardownWorkflow, BUILT_IN_BUNDLES, CLAUDE_RULE_TARGET, COMPLETE_JOB_ID, DEFAULT_PRIORITY_LABELS, DEFAULT_STATUS_LABELS, DEFAULT_TEARDOWN_BRANCH_PATTERNS, DEFAULT_TYPE_LABELS, JsiiFaker, MCP_TRANSPORT, MERGE_METHODS, MIMIMUM_RELEASE_AGE, MINIMUM_RELEASE_AGE, MonorepoProject, PROD_DEPLOY_NAME, PnpmWorkspace, ProjectMetadata, REQUIREMENTS_WRITER_PATHS, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, ResetTask, StarlightProject, TestRunner, TurboRepo, TurboRepoTask, TypeScriptConfig, TypeScriptProject, VERSION, VERSION_KEYS_SKIP, VERSION_NPM_PACKAGES, VSCodeConfig, Vitest, addApproveMergeUpgradeWorkflow, addBuildCompleteJob, addSyncLabelsWorkflow, awsCdkBundle, baseBundle, bcmWriterBundle, companyProfileBundle, getLatestEligibleVersion, githubWorkflowBundle, industryDiscoveryBundle, jestBundle, maintenanceAuditBundle, meetingAnalysisBundle, orchestratorBundle, peopleProfileBundle, pnpmBundle, prReviewBundle, projenBundle, requirementsAnalystBundle, requirementsReviewerBundle, requirementsWriterBundle, researchPipelineBundle, resolveModelAlias, resolveTemplateVariables, slackBundle, softwareProfileBundle, turborepoBundle, typescriptBundle, vitestBundle };
-export type { AgentConfigOptions, AgentModel, AgentPlatform, AgentPlatformOverrides, AgentProcedure, AgentRule, AgentRuleBundle, AgentRuleScope, AgentSkill, AgentSubAgent, AgentSubAgentPlatformOverrides, ApproveMergeUpgradeOptions, AstroConfigOptions, AstroIntegrationSpec, AstroProjectOptions, AwsAccount, AwsCdkProjectOptions, AwsDeploymentTargetOptions, AwsLocalDeploymentConfig, AwsOrganization, AwsRegion, AwsTeardownWorkflowOptions, CiDeploymentConfig, ClassTypeOptions, ClaudeAutoModeConfig, ClaudeHookAction, ClaudeHookEntry, ClaudeHooksConfig, ClaudePermissionsConfig, ClaudeRuleTarget, ClaudeSandboxConfig, ClaudeSettingsConfig, CopilotHandoff, CursorHookAction, CursorHooksConfig, CursorSettingsConfig, DeployWorkflowOptions, DeploymentMetadata, GitBranch, GitHubBoardMetadata, GitHubProjectMetadata, GitHubSprintMetadata, IDependencyResolver, LabelDefinition, McpServerConfig, McpTransport, MergeMethod, MonorepoProjectOptions, OrganizationMetadata, PnpmWorkspaceOptions, ProjectMetadataOptions, RemoteCacheOptions, RepositoryMetadata, ResetTaskOptions, ResolvedProjectMetadata, SlackMetadata, StarlightEditLink, StarlightLogo, StarlightProjectOptions, StarlightSidebarItem, StarlightSocialLink, SyncLabelsOptions, TemplateResolveResult, TurboRepoOptions, TurboRepoTaskOptions, TypeScriptProjectOptions, VersionKey, VitestConfigOptions, VitestOptions };
+export { AGENT_MODEL, AGENT_PLATFORM, AGENT_RULE_SCOPE, AgentConfig, AstroConfig, AstroOutput, AstroProject, AwsCdkProject, AwsDeployWorkflow, AwsDeploymentConfig, AwsDeploymentTarget, AwsTeardownWorkflow, BUILT_IN_BUNDLES, CLAUDE_RULE_TARGET, COMPLETE_JOB_ID, DEFAULT_PRIORITY_LABELS, DEFAULT_STATUS_LABELS, DEFAULT_TEARDOWN_BRANCH_PATTERNS, DEFAULT_TYPE_LABELS, JsiiFaker, LAYOUT_ENFORCEMENT, LAYOUT_ROOT_BY_PROJECT_TYPE, MCP_TRANSPORT, MERGE_METHODS, MIMIMUM_RELEASE_AGE, MINIMUM_RELEASE_AGE, MONOREPO_LAYOUT, MonorepoProject, PROD_DEPLOY_NAME, PnpmWorkspace, ProjectMetadata, REQUIREMENTS_WRITER_PATHS, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, ResetTask, StarlightProject, TestRunner, TurboRepo, TurboRepoTask, TypeScriptConfig, TypeScriptProject, VERSION, VERSION_KEYS_SKIP, VERSION_NPM_PACKAGES, VSCodeConfig, Vitest, addApproveMergeUpgradeWorkflow, addBuildCompleteJob, addSyncLabelsWorkflow, awsCdkBundle, baseBundle, bcmWriterBundle, companyProfileBundle, formatLayoutViolation, getLatestEligibleVersion, githubWorkflowBundle, industryDiscoveryBundle, jestBundle, maintenanceAuditBundle, meetingAnalysisBundle, orchestratorBundle, peopleProfileBundle, pnpmBundle, prReviewBundle, projenBundle, requirementsAnalystBundle, requirementsReviewerBundle, requirementsWriterBundle, researchPipelineBundle, resolveModelAlias, resolveTemplateVariables, slackBundle, softwareProfileBundle, turborepoBundle, typescriptBundle, validateMonorepoLayout, vitestBundle };
+export type { AgentConfigOptions, AgentModel, AgentPlatform, AgentPlatformOverrides, AgentProcedure, AgentRule, AgentRuleBundle, AgentRuleScope, AgentSkill, AgentSubAgent, AgentSubAgentPlatformOverrides, ApproveMergeUpgradeOptions, AstroConfigOptions, AstroIntegrationSpec, AstroProjectOptions, AwsAccount, AwsCdkProjectOptions, AwsDeploymentTargetOptions, AwsLocalDeploymentConfig, AwsOrganization, AwsRegion, AwsTeardownWorkflowOptions, CiDeploymentConfig, ClassTypeOptions, ClaudeAutoModeConfig, ClaudeHookAction, ClaudeHookEntry, ClaudeHooksConfig, ClaudePermissionsConfig, ClaudeRuleTarget, ClaudeSandboxConfig, ClaudeSettingsConfig, CopilotHandoff, CursorHookAction, CursorHooksConfig, CursorSettingsConfig, DeployWorkflowOptions, DeploymentMetadata, GitBranch, GitHubBoardMetadata, GitHubProjectMetadata, GitHubSprintMetadata, IDependencyResolver, LabelDefinition, LayoutEnforcement, LayoutViolation, McpServerConfig, McpTransport, MergeMethod, MonorepoLayoutRoot, MonorepoProjectOptions, OrganizationMetadata, PnpmWorkspaceOptions, ProjectMetadataOptions, RemoteCacheOptions, RepositoryMetadata, ResetTaskOptions, ResolvedProjectMetadata, SlackMetadata, StarlightEditLink, StarlightLogo, StarlightProjectOptions, StarlightSidebarItem, StarlightSocialLink, SyncLabelsOptions, TemplateResolveResult, TurboRepoOptions, TurboRepoTaskOptions, TypeScriptProjectOptions, VersionKey, VitestConfigOptions, VitestOptions };

package/lib/index.js

@@ -195,10 +195,13 @@ __export(index_exports, {
   DEFAULT_TEARDOWN_BRANCH_PATTERNS: () => DEFAULT_TEARDOWN_BRANCH_PATTERNS,
   DEFAULT_TYPE_LABELS: () => DEFAULT_TYPE_LABELS,
   JsiiFaker: () => JsiiFaker,
+  LAYOUT_ENFORCEMENT: () => LAYOUT_ENFORCEMENT,
+  LAYOUT_ROOT_BY_PROJECT_TYPE: () => LAYOUT_ROOT_BY_PROJECT_TYPE,
   MCP_TRANSPORT: () => MCP_TRANSPORT,
   MERGE_METHODS: () => MERGE_METHODS,
   MIMIMUM_RELEASE_AGE: () => MIMIMUM_RELEASE_AGE,
   MINIMUM_RELEASE_AGE: () => MINIMUM_RELEASE_AGE,
+  MONOREPO_LAYOUT: () => MONOREPO_LAYOUT,
   MonorepoProject: () => MonorepoProject,
   PROD_DEPLOY_NAME: () => PROD_DEPLOY_NAME,
   PnpmWorkspace: () => PnpmWorkspace,
@@ -225,6 +228,7 @@ __export(index_exports, {
   baseBundle: () => baseBundle,
   bcmWriterBundle: () => bcmWriterBundle,
   companyProfileBundle: () => companyProfileBundle,
+  formatLayoutViolation: () => formatLayoutViolation,
   getLatestEligibleVersion: () => getLatestEligibleVersion,
   githubWorkflowBundle: () => githubWorkflowBundle,
   industryDiscoveryBundle: () => industryDiscoveryBundle,
@@ -246,6 +250,7 @@ __export(index_exports, {
   softwareProfileBundle: () => softwareProfileBundle,
   turborepoBundle: () => turborepoBundle,
   typescriptBundle: () => typescriptBundle,
+  validateMonorepoLayout: () => validateMonorepoLayout,
   vitestBundle: () => vitestBundle
 });
 module.exports = __toCommonJS(index_exports);
@@ -845,6 +850,91 @@ var baseBundle = {
       ].join("\n"),
       tags: ["workflow"]
     },
+    {
+      name: "monorepo-layout",
+      description: "Canonical monorepo top-level folders (docs, apps, packages, sites), the @ownerscope/<name> scoping rule, the docs-singleton carve-out, and the scaffolding skills that place new sub-projects",
+      scope: AGENT_RULE_SCOPE.ALWAYS,
+      content: [
+        "# Monorepo Layout",
+        "",
+        "Every monorepo built with `@codedrifters/configulator` uses a single,",
+        "fixed top-level folder layout. Agents, scaffolding skills, pnpm-workspace",
+        "globs, Turbo filters, and CI cache keys all assume these roots.",
+        "",
+        "## Four Canonical Top-Level Folders",
+        "",
+        "| Folder | Purpose | Examples |",
+        "|--------|---------|----------|",
+        "| `/docs` | **Single** Starlight site covering the entire monorepo. The one site that lives outside `/sites`. | Monorepo-wide developer docs, ADRs, how-to guides. |",
+        "| `/apps/@scope/<name>` | Deployable applications \u2014 anything that runs or ships as a running process. | AWS CDK stacks, mobile apps (iOS/Android), backend services. |",
+        "| `/packages/@scope/<name>` | Shared libraries \u2014 published npm packages and workspace-internal libraries. | `@codedrifters/configulator`, `@codedrifters/constructs`, `@codedrifters/utils`. |",
+        "| `/sites/@scope/<name>` | User-facing web front ends that are **not** the monorepo-wide docs site. | Marketing sites, SPAs, per-client static sites. |",
+        "",
+        "No other top-level folder is part of this contract. Generated roots",
+        "(`.projen/`, `.github/`, `node_modules/`, `.turbo/`, etc.) are orthogonal",
+        "and unchanged.",
+        "",
+        "## Scoping Rule",
+        "",
+        "Every sub-project under `apps/`, `packages/`, or `sites/` is named",
+        "`@ownerscope/<name>`, where **scope is the owning party** (not a category).",
+        "",
+        "- `@codedrifters/configulator` \u2014 a shared library owned by CodeDrifters \u2192 `packages/@codedrifters/configulator`",
+        "- `@codedrifters/infrastructure-stack` \u2014 an AWS CDK app owned by CodeDrifters \u2192 `apps/@codedrifters/infrastructure-stack`",
+        "- `@clientA/iphone-app` \u2014 a mobile app owned by Client A \u2192 `apps/@clientA/iphone-app`",
+        "- `@clientB/marketing-site` \u2014 a marketing site owned by Client B \u2192 `sites/@clientB/marketing-site`",
+        "",
+        "The scope identifies **who owns the sub-project**, not what kind of",
+        "sub-project it is. Kind is captured by the top-level folder (`apps/`,",
+        "`packages/`, `sites/`). Never scope by category (e.g. `@apps/foo`,",
+        "`@libs/bar`) \u2014 the top-level folder already carries that information.",
+        "",
+        "## Docs-Singleton Carve-Out",
+        "",
+        "There is **exactly one** Starlight docs site per monorepo, and it lives",
+        "at `/docs`. It is **not** `sites/@scope/docs`.",
+        "",
+        "- The docs site is monorepo-wide. Sub-project documentation belongs",
+        "  inside that single site (under `docs/content/`), not in a per-package",
+        "  `docs/` folder.",
+        "- Configulator's `StarlightProject` defaults its `outdir` to `/docs`.",
+        "- `/sites` is reserved for end-user-facing web front ends (marketing",
+        "  sites, SPAs, client-facing apps). It deliberately does not host the",
+        "  dev-docs site.",
+        "",
+        "## Project-Type \u2192 `outdir` Mapping",
+        "",
+        "Configulator project types default their `outdir` according to the",
+        "following table. Override `outdir` explicitly only when you have a",
+        "genuine reason \u2014 the defaults cover the common path.",
+        "",
+        "| Configulator project type | Default `outdir` |",
+        "|---------------------------|------------------|",
+        "| `TypeScriptProject` | `packages/<scope>/<name>` |",
+        "| `AwsCdkProject` | `apps/<scope>/<name>` |",
+        "| `AstroProject` | `sites/<scope>/<name>` |",
+        "| `StarlightProject` (role = docs) | `docs/` |",
+        "",
+        "`<scope>` is parsed from the sub-project's package name (everything",
+        "after `@` and before `/`). `<name>` is the unscoped part of the",
+        "package name.",
+        "",
+        "## Placing New Sub-Projects",
+        "",
+        "Never hand-roll a sub-project path. Use one of the scaffolding skills,",
+        "which take `@scope/<name>` as input, validate it, and place the new",
+        "project in the correct folder:",
+        "",
+        "- `/create-package` \u2014 scaffolds a new `TypeScriptProject` under `packages/<scope>/<name>`",
+        "- `/create-app` \u2014 scaffolds a new `AwsCdkProject` under `apps/<scope>/<name>`",
+        "- `/create-site` \u2014 scaffolds a new `AstroProject` under `sites/<scope>/<name>`",
+        "",
+        "The monorepo-wide docs site at `/docs` is a singleton and is created",
+        "once per repo via `StarlightProject` \u2014 it is not scaffolded per",
+        "sub-project."
+      ].join("\n"),
+      tags: ["project"]
+    },
     {
       name: "issue-conventions",
       description: "Issue title prefixes, GitHub issue type mapping, prerequisite issues",
@@ -15556,6 +15646,77 @@ var import_javascript3 = require("projen/lib/javascript");
 var import_typescript3 = require("projen/lib/typescript");
 var import_ts_deepmerge = require("ts-deepmerge");
 
+// src/projects/monorepo-layout.ts
+var MONOREPO_LAYOUT = {
+  DOCS: "docs",
+  APPS: "apps",
+  PACKAGES: "packages",
+  SITES: "sites"
+};
+var LAYOUT_ENFORCEMENT = {
+  OFF: "off",
+  WARN: "warn",
+  ERROR: "error"
+};
+var LAYOUT_ROOT_BY_PROJECT_TYPE = {
+  TypeScriptProject: MONOREPO_LAYOUT.PACKAGES,
+  AwsCdkProject: MONOREPO_LAYOUT.APPS,
+  AstroProject: MONOREPO_LAYOUT.SITES,
+  StarlightProject: MONOREPO_LAYOUT.DOCS
+};
+function validateMonorepoLayout(root) {
+  const violations = [];
+  const rootOutdir = toPosix(root.outdir);
+  for (const sub of root.subprojects) {
+    const className = sub.constructor.name;
+    const expectedRoot = LAYOUT_ROOT_BY_PROJECT_TYPE[className];
+    if (expectedRoot === void 0) {
+      continue;
+    }
+    const relOutdir = relativeOutdir(rootOutdir, toPosix(sub.outdir));
+    if (!outdirMatchesRoot(relOutdir, expectedRoot)) {
+      violations.push({
+        projectName: sub.name,
+        projectType: className,
+        outdir: relOutdir,
+        expectedRoot
+      });
+    }
+  }
+  return violations;
+}
+function formatLayoutViolation(violation) {
+  const { projectName, projectType, outdir, expectedRoot } = violation;
+  const expectedExample = expectedRoot === MONOREPO_LAYOUT.DOCS ? "docs/" : `${expectedRoot}/<scope>/<name>`;
+  return `[monorepo-layout] ${projectType} "${projectName}" has outdir "${outdir}", which is outside the expected root "${expectedRoot}/" (expected e.g. "${expectedExample}"). See docs/requirements/architectural-decisions/ADR-006-monorepo-layout.md.`;
+}
+function outdirMatchesRoot(relOutdir, expectedRoot) {
+  const segments = relOutdir.split("/").filter((s) => s.length > 0);
+  if (segments.length === 0) {
+    return false;
+  }
+  if (segments[0] !== expectedRoot) {
+    return false;
+  }
+  if (expectedRoot === MONOREPO_LAYOUT.DOCS) {
+    return true;
+  }
+  return segments.length >= 2;
+}
+function toPosix(p) {
+  return p.replace(/\\/g, "/");
+}
+function relativeOutdir(rootOutdir, subOutdir) {
+  if (subOutdir === rootOutdir) {
+    return "";
+  }
+  const prefix2 = rootOutdir.endsWith("/") ? rootOutdir : `${rootOutdir}/`;
+  if (subOutdir.startsWith(prefix2)) {
+    return subOutdir.slice(prefix2.length);
+  }
+  return subOutdir;
+}
+
 // src/tasks/reset-task.ts
 var import_projen13 = require("projen");
 var ResetTask = class _ResetTask extends import_projen13.Component {
@@ -16064,6 +16225,11 @@ var MonorepoProject = class extends import_typescript3.TypeScriptAppProject {
        * By default treat as a registry consumer (upgrade workflow syncs configulator).
        */
       configulatorRegistryConsumer: true,
+      /**
+       * ADR-006 layout enforcement defaults to "warn" during rollout so
+       * legacy outdirs log actionable warnings but do not break synth.
+       */
+      layoutEnforcement: LAYOUT_ENFORCEMENT.WARN,
       /**
        * We don't want sample code generated for the root project.
        */
@@ -16177,6 +16343,7 @@ var MonorepoProject = class extends import_typescript3.TypeScriptAppProject {
     this.tsconfig?.removeInclude(`${this.srcdir}/**/*.ts`);
     this.pnpmVersion = options.pnpmVersion;
     this.configulatorRegistryConsumer = options.configulatorRegistryConsumer ?? true;
+    this.layoutEnforcement = options.layoutEnforcement ?? LAYOUT_ENFORCEMENT.WARN;
     new VSCodeConfig(this);
     new PnpmWorkspace(this, options.pnpmOptions?.pnpmWorkspaceOptions);
     if (options.turbo) {
@@ -16271,6 +16438,32 @@ var MonorepoProject = class extends import_typescript3.TypeScriptAppProject {
       );
     }
   }
+  /**
+   * Validate sub-project `outdir` values against the ADR-006 monorepo
+   * layout contract. Runs in `preSynthesize` so all sub-projects are
+   * attached by the time we inspect the tree.
+   *
+   * Behavior is controlled by `layoutEnforcement`:
+   * - `"off"`  — skip validation.
+   * - `"warn"` — log a `console.warn` per violation; continue.
+   * - `"error"` — throw on the first violation.
+   */
+  preSynthesize() {
+    super.preSynthesize();
+    if (this.layoutEnforcement === LAYOUT_ENFORCEMENT.OFF) {
+      return;
+    }
+    const violations = validateMonorepoLayout(this);
+    if (violations.length === 0) {
+      return;
+    }
+    if (this.layoutEnforcement === LAYOUT_ENFORCEMENT.ERROR) {
+      throw new Error(formatLayoutViolation(violations[0]));
+    }
+    for (const violation of violations) {
+      console.warn(formatLayoutViolation(violation));
+    }
+  }
   /**
    * Allows a sub project to request installation of dependency at the Monorepo root
    * They must provide a function that is executed after dependencies have been installed
@@ -17388,10 +17581,13 @@ var TypeScriptConfig = class extends import_projen22.Component {
   DEFAULT_TEARDOWN_BRANCH_PATTERNS,
   DEFAULT_TYPE_LABELS,
   JsiiFaker,
+  LAYOUT_ENFORCEMENT,
+  LAYOUT_ROOT_BY_PROJECT_TYPE,
   MCP_TRANSPORT,
   MERGE_METHODS,
   MIMIMUM_RELEASE_AGE,
   MINIMUM_RELEASE_AGE,
+  MONOREPO_LAYOUT,
   MonorepoProject,
   PROD_DEPLOY_NAME,
   PnpmWorkspace,
@@ -17418,6 +17614,7 @@ var TypeScriptConfig = class extends import_projen22.Component {
   baseBundle,
   bcmWriterBundle,
   companyProfileBundle,
+  formatLayoutViolation,
   getLatestEligibleVersion,
   githubWorkflowBundle,
   industryDiscoveryBundle,
@@ -17439,6 +17636,7 @@ var TypeScriptConfig = class extends import_projen22.Component {
   softwareProfileBundle,
   turborepoBundle,
   typescriptBundle,
+  validateMonorepoLayout,
   vitestBundle
 });
 //# sourceMappingURL=index.js.map