@codedrifters/configulator 0.0.314 → 0.0.315

package/lib/index.d.mts

@@ -9519,6 +9519,29 @@ interface RemoteCacheOptions {
      */
     readonly teamName: string;
 }
+/**
+ * Options for {@link TurboRepo.activateBranchNameEnvVar}.
+ *
+ * The `tasks` field is required so callers explicitly name every task whose
+ * cache hash should include `GIT_BRANCH_NAME`. Scoping the env to a small
+ * set of consuming tasks (typically CDK `synth` / `package`) preserves
+ * cross-branch cache hits for every other task in the monorepo — library
+ * `compile` / `test` / `lint` / `package` runs no longer miss cache just
+ * because the branch name changed.
+ */
+interface ActivateBranchNameEnvVarOptions {
+    /**
+     * Tasks whose cache hash should include GIT_BRANCH_NAME. Each named task
+     * gets the env added to its `env: []` array. Unknown task names throw at
+     * synth time so typos surface immediately.
+     *
+     * Adding a task to this list is a deliberate cache-hit-rate tradeoff:
+     * the task will miss cache on every branch switch. Only name tasks that
+     * actually read `GIT_BRANCH_NAME` at runtime (e.g. CDK stack-name
+     * generators that bake the branch into resource names).
+     */
+    readonly tasks: Array<string>;
+}
 interface TurboRepoOptions {
     /**
      * Version of turborepo to use.
@@ -9859,11 +9882,24 @@ declare class TurboRepo extends Component$1 {
      */
     addGlobalEnvVar(name: string, value: string): void;
     /**
-     * Sets GIT_BRANCH_NAME so root tasks (e.g. build:all) pass the current branch.
-     * Value must be exactly $(...) so Projen's task runtime expands it; the shell
-     * then expands ${GIT_BRANCH_NAME:-$(git rev-parse --abbrev-ref HEAD)}.
+     * @deprecated Pass `{ tasks: [...] }` and name only the tasks whose cache
+     * hash must include `GIT_BRANCH_NAME`. The no-args form writes the env to
+     * the root `globalEnv` array, which forces every task in the monorepo to
+     * miss cache on every branch switch — destroying cross-branch cache hits
+     * for library `compile` / `test` / `lint` / `package` work that does not
+     * read the branch name at runtime.
      */
     activateBranchNameEnvVar(): void;
+    /**
+     * Scopes `GIT_BRANCH_NAME` to the named tasks on this TurboRepo. The env
+     * is written to each task's `env: []` array so only those tasks miss
+     * cache on a branch switch. Other tasks (and the root `globalEnv`) are
+     * left untouched.
+     *
+     * Throws at synth time when `options.tasks` contains a name that does
+     * not match a task on this TurboRepo, so typos surface immediately.
+     */
+    activateBranchNameEnvVar(options: ActivateBranchNameEnvVarOptions): void;
     preSynthesize(): void;
 }
 
@@ -10668,4 +10704,4 @@ declare function pinPnpmActionSetup(project: Project$1): void;
  */
 declare function pinSetupNodeVersion(project: Project$1): void;
 
-export { AGENT_MODEL, AGENT_PLATFORM, AGENT_REGISTRY_ENTRIES, AGENT_RULE_SCOPE, AGENT_TIER_ROLES, AGENT_TIER_VALUES, AUDIT_CATEGORY_ORDER, type AddStorybookOptions, type AgentCommand, AgentConfig, type AgentConfigOptions, type AgentExpansionRules, type AgentFeaturesConfig, type AgentModel, type AgentPathsConfig, type AgentPlatform, type AgentPlatformOverrides, type AgentProcedure, type AgentRegistryEntry, type AgentRule, type AgentRuleBundle, type AgentRuleScope, type AgentSkill, type AgentSubAgent, type AgentSubAgentPlatformOverrides, type AgentTier, type AgentTierConfig, type AgentTierEntry, type AnalyzeTsDocCoverageOptions, type ApiDiffCheckOptions, type ApiDiffFinding, type ApiDiffResult, ApiExtractor, type ApiExtractorOptions, type ApiExtractorReportOptions, type ApiSurfaceEntry, type ApproveMergeUpgradeOptions, AstroConfig, type AstroConfigOptions, type AstroIntegrationSpec, AstroOutput, AstroProject, type AstroProjectOptions, AuditCategory, type AuditCheckRunner, type AuditCheckRunnerContext, type AuditFinding, type AuditFindingBase, type AuditLocation, AuditMode, type AuditReport, AuditSeverity, type AwsAccount, AwsCdkProject, type AwsCdkProjectOptions, AwsDeployWorkflow, AwsDeploymentConfig, AwsDeploymentTarget, type AwsDeploymentTargetOptions, type AwsLocalDeploymentConfig, type AwsOrganization, type AwsRegion, AwsTeardownWorkflow, type AwsTeardownWorkflowOptions, BUILT_IN_BUNDLES, BUNDLE_OWNERSHIP, type BundleOwnership, CLAUDE_RULE_TARGET, COMPLETE_JOB_ID, type CiDeploymentConfig, type ClassTypeOptions, type ClaudeAutoModeConfig, type ClaudeHookAction, type ClaudeHookEntry, type ClaudeHooksConfig, type ClaudeMdConfig, type ClaudePermissionsConfig, type ClaudeRuleTarget, type ClaudeSandboxConfig, type ClaudeSettingsConfig, type CompileFencedSamplesOptions, type CopilotHandoff, type CursorHookAction, type CursorHooksConfig, type CursorSettingsConfig, type CustomDocSection, DEFAULT_AC_THRESHOLDS, DEFAULT_AGENT_PATHS, DEFAULT_AGENT_TIERS, DEFAULT_API_EXTRACTOR_CONFIG_FILE, DEFAULT_API_EXTRACTOR_ENTRY_POINT, DEFAULT_API_EXTRACTOR_REPORT_FILENAME, DEFAULT_API_EXTRACTOR_REPORT_FOLDER, DEFAULT_AUDIT_REPORT_DIR, DEFAULT_BUNDLE_OVERRIDES, DEFAULT_DECOMPOSITION_TEMPLATE, DEFAULT_DISPATCH_MODEL, DEFAULT_DISPATCH_TO_HOUSEKEEPING_RATIO, DEFAULT_HOUSEKEEPING_MODEL, DEFAULT_ISSUE_PRIORITY, DEFAULT_ISSUE_STATUS, DEFAULT_ISSUE_TEMPLATES_BUNDLE_PATH_PATTERNS, DEFAULT_ISSUE_TEMPLATES_EMIT_CHECKER, DEFAULT_ISSUE_TEMPLATES_EMIT_STARTER, DEFAULT_ISSUE_TEMPLATES_ENABLED, DEFAULT_ISSUE_TEMPLATES_PATH, DEFAULT_ISSUE_TEMPLATES_REQUIRE_REFERENCE, DEFAULT_OFF_PEAK_CRON_EXAMPLE, DEFAULT_PARTIAL_UNBLOCK_COMMENT_TEMPLATE, DEFAULT_PRIORITY_LABELS, DEFAULT_PRODUCT_CONTEXT_PATH, DEFAULT_PROGRESS_FILES_ENABLED, DEFAULT_PROGRESS_FILES_FILENAME_PATTERN, DEFAULT_PROGRESS_FILES_FORMAT, DEFAULT_PROGRESS_FILES_STALE_AFTER_HOURS, DEFAULT_PROGRESS_FILES_STATE_DIR, DEFAULT_REQUIRE_PRODUCT_CONTEXT, DEFAULT_RESOLVED_ISSUE_DEFAULTS, DEFAULT_SAMPLE_COMPILER_OPTIONS, DEFAULT_SCHEDULED_TASKS_ROOT, DEFAULT_SCHEDULED_TASK_ENTRIES, DEFAULT_SHARED_EDITING_CONFLICT_STRATEGY, DEFAULT_SHARED_EDITING_EMIT_HELPER, DEFAULT_SHARED_EDITING_ENABLED, DEFAULT_SHARED_EDITING_VERIFY_COMMIT, DEFAULT_SHARED_INDEX_PATHS, DEFAULT_SKILL_EVALS_EMIT_RUNNER, DEFAULT_SKILL_EVALS_ENABLED, DEFAULT_SKILL_EVALS_SKILLS_ROOT, DEFAULT_SOURCES_THRESHOLDS, DEFAULT_STATE_FILE_PATH, DEFAULT_STATUS_LABELS, DEFAULT_TEARDOWN_BRANCH_PATTERNS, DEFAULT_TEMPORAL_FRAMING_CADENCES, DEFAULT_TEMPORAL_FRAMING_EMIT_CHECKER, DEFAULT_TEMPORAL_FRAMING_ENABLED, DEFAULT_TEMPORAL_FRAMING_PATHS, DEFAULT_TYPE_LABELS, DEFAULT_UNBLOCK_COMMENT_TEMPLATE, DEFAULT_UNBLOCK_DEPENDENTS_ENABLED, DEFAULT_UPSTREAM_CONFIGULATOR_ENABLED, DOCS_SYNC_AUDIT_SCHEMA_VERSION, type DeployWorkflowOptions, type DeploymentMetadata, type DocReferenceRecord, type EffectiveScopeThresholds, type ExtractDocReferencesOptions, type ExtractFencedSamplesOptions, type FencedSampleRecord, type FocusArea, type FocusAreaMatch, type FocusConfig, type GitBranch, type GitHubBoardMetadata, type GitHubProjectMetadata, type GitHubSprintMetadata, type IDependencyResolver, type IssueDefaultsConfig, type IssueDefaultsOverride, type IssueDefaultsPriority, type IssueDefaultsStatus, type IssueTemplatesConfig, JsiiFaker, LAYOUT_ENFORCEMENT, LAYOUT_ROOT_BY_PROJECT_TYPE, type LabelDefinition, type LayoutEnforcement, type LayoutViolation, type LinkFailureFinding, MAX_LABEL_DESCRIPTION_LENGTH, MCP_TRANSPORT, MERGE_METHODS, MIMIMUM_RELEASE_AGE, MINIMUM_RELEASE_AGE, MONOREPO_LAYOUT, type McpServerConfig, type McpTransport, type MeetingArea, type MeetingScope, type MeetingType, type MeetingTypeKind, type MeetingsConfig, type MergeMethod, type MonorepoLayoutRoot, MonorepoProject, type MonorepoProjectOptions, Nvmrc, type OrganizationMetadata, PROD_DEPLOY_NAME, PROGRESS_FILES_FORMAT_VALUES, PnpmWorkspace, type PnpmWorkspaceOptions, type PriorityRule, type ProgressFilesConfig, ProjectMetadata, type ProjectMetadataOptions, REQUIREMENTS_WRITER_PATHS, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, ReactViteSiteProject, type ReactViteSiteProjectOptions, type ReferenceMismatchCheckOptions, type ReferenceMismatchFinding, type RemoteCacheOptions, type RepositoryMetadata, ResetTask, type ResetTaskOptions, type ResolvedAgentPaths, type ResolvedAgentTier, type ResolvedIssueDefaults, type ResolvedIssueDefaultsEntry, type ResolvedIssueTemplates, type ResolvedProgressFiles, type ResolvedProjectMetadata, type ResolvedRunRatio, type ResolvedScheduledTask, type ResolvedScheduledTasks, type ResolvedScopeGate, type ResolvedScopeGateBundleOverride, type ResolvedSharedEditing, type ResolvedSkillEvals, type ResolvedTemporalFraming, type ResolvedUnblockDependents, type RunRatioConfig, type RunScanOptions, type RunScanResult, SCHEDULED_TASK_MODEL_VALUES, SCOPE_CLASS_VALUES, SHARED_EDITING_CONFLICT_STRATEGY_VALUES, STARLIGHT_ROLE, SUPPRESSED_WORKFLOW_RULE_NAMES, type SampleCompilationFailure, type SampleFailureFinding, SampleLang, type ScheduledTaskEntry, type ScheduledTaskModel, type ScheduledTaskOverride, type ScheduledTasksConfig, type ScopeClass, type ScopeGateBundleOverride, type ScopeGateConfig, type ScopeGateThresholds, type SharedEditingConfig, type SkillEvalsConfig, type SlackMetadata, type SourceTierExamples, type StarlightEditLink, type StarlightLogo, StarlightProject, type StarlightProjectOptions, type StarlightRole, type StarlightSidebarItem, type StarlightSingletonViolation, type StarlightSocialLink, type SyncLabelsOptions, TEMPORAL_FRAMING_CATEGORY_VALUES, type TemplateResolveResult, type TemporalFramingCategory, type TemporalFramingConfig, TestRunner, TsDocCoverageKind, type TsDocCoverageRecord, type TsdocCoverageCheckOptions, type TsdocCoverageFinding, TurboRepo, type TurboRepoOptions, TurboRepoTask, type TurboRepoTaskOptions, TypeScriptConfig, TypeScriptProject, type TypeScriptProjectOptions, UNKNOWN_TYPE_FALLBACK_TIER, type UnblockDependentsConfig, type UpstreamConfigulatorConfig, VALID_PRIORITY_VALUES, VALID_STATUS_VALUES, VERSION, VERSION_KEYS_SKIP, VERSION_NPM_PACKAGES, VSCodeConfig, type VersionKey, Vitest, type VitestConfigOptions, type VitestOptions, addApproveMergeUpgradeWorkflow, addBuildCompleteJob, addPlaywright, addStorybook, addSyncLabelsWorkflow, agendaBundle, analyzeTsDocCoverage, auditReportJsonSchema, awsCdkBundle, baseBundle, bcmWriterBundle, buildAgentRegistryRule, buildBaseBundle, buildBcmWriterBundle, buildBuiltInBundles, buildBusinessModelsBundle, buildCheckBlockedProcedure, buildCompanyProfileBundle, buildCustomerProfileBundle, buildDocsSyncBundle, buildIndustryDiscoveryBundle, buildMaintenanceAuditBundle, buildMeetingAnalysisBundle, buildOrchestratorConventionsContent, buildPeopleProfileBundle, buildRegulatoryResearchBundle, buildReport, buildRequirementsAnalystBundle, buildRequirementsReviewerBundle, buildRequirementsWriterBundle, buildResearchPipelineBundle, buildSoftwareProfileBundle, buildStandardsResearchBundle, buildUnblockDependentsProcedure, bundleNameForWorkflowRule, businessModelsBundle, checkDocSamplesProcedure, checkLinksProcedure, classifyIssueScope, classifyRun, companyProfileBundle, compileFencedSamples, createApiDiffCheck, createReferenceMismatchCheck, createTsdocCoverageCheck, customerProfileBundle, diffApiRollups, docsSyncBundle, emptyCategoryBuckets, extractApiProcedure, extractDocReferences, extractFencedSamples, formatLayoutViolation, formatStarlightSingletonViolation, getLatestEligibleVersion, githubWorkflowBundle, hasAnyDocsEmittingBundle, hasAnyDownstreamIssueKindBundle, industryDiscoveryBundle, isPhaseLabelOwnedByExcluded, isScheduledTaskOwnedByExcluded, isSuppressedWorkflowRule, isTypeLabelOwnedByExcluded, jestBundle, labelsForPhase, maintenanceAuditBundle, meetingAnalysisBundle, orchestratorBundle, parseApiRollup, peopleProfileBundle, persistAuditReport, pinPnpmActionSetup, pinSetupNodeVersion, pnpmBundle, prReviewBundle, projenBundle, referenceRecordToFinding, regulatoryResearchBundle, renderAgentTierCaseStatement, renderAgentTierSection, renderCheckDocSamplesProcedure, renderCheckLinksProcedure, renderCustomDocSectionBlock, renderCustomDocSections, renderExtractApiProcedure, renderFocusSection, renderIssueTemplatesBundleHook, renderIssueTemplatesCheckerScript, renderIssueTemplatesRuleContent, renderIssueTemplatesStarterPage, renderMeetingTypesSection, renderPriorityRulesSection, renderProgressFileName, renderProgressFilePath, renderProgressFilesBundleHook, renderProgressFilesRuleContent, renderRunRatioSection, renderRunRatioShellHelpers, renderScheduledTaskSkillFile, renderScheduledTasksSection, renderScopeGateSection, renderScopeGateShellHelpers, renderSharedEditingBundleHook, renderSharedEditingHelperScript, renderSharedEditingRuleContent, renderSkillEvalsBundleHook, renderSkillEvalsRuleContent, renderSkillEvalsRunnerScript, renderSourceTierExamples, renderStubIndexConventionRuleContent, renderTemporalFramingCheckerScript, renderTemporalFramingRuleContent, renderUnblockDependentsScript, renderUnblockDependentsSection, requirementsAnalystBundle, requirementsReviewerBundle, requirementsWriterBundle, researchPipelineBundle, resolveAgentPaths, resolveAgentTiers, resolveAstroProjectOutdir, resolveAwsCdkProjectOutdir, resolveIssueDefaults, resolveIssueTemplates, resolveModelAlias, resolveOrchestratorAssets, resolveOutdirFromPackageName, resolveOverrideForLabels, resolveProgressFiles, resolveReactViteSiteProjectOutdir, resolveRunRatio, resolveScheduledTasks, resolveScopeGate, resolveSharedEditing, resolveSkillEvals, resolveTemplateVariables, resolveTemporalFraming, resolveTypeScriptProjectOutdir, resolveUnblockDependents, runScan, slackBundle, softwareProfileBundle, standardsResearchBundle, tsdocRecordToFindings, turborepoBundle, typescriptBundle, upstreamConfigulatorDocsBundle, validateAgentTierConfig, validateIssueDefaultsConfig, validateIssueTemplatesConfig, validateMonorepoLayout, validateProgressFilesConfig, validateRunRatioConfig, validateScheduledTasksConfig, validateScopeGateConfig, validateSharedEditingConfig, validateSkillEvalsConfig, validateStarlightSingleton, validateTemporalFramingConfig, validateUnblockDependentsConfig, vitestBundle };
+export { AGENT_MODEL, AGENT_PLATFORM, AGENT_REGISTRY_ENTRIES, AGENT_RULE_SCOPE, AGENT_TIER_ROLES, AGENT_TIER_VALUES, AUDIT_CATEGORY_ORDER, type ActivateBranchNameEnvVarOptions, type AddStorybookOptions, type AgentCommand, AgentConfig, type AgentConfigOptions, type AgentExpansionRules, type AgentFeaturesConfig, type AgentModel, type AgentPathsConfig, type AgentPlatform, type AgentPlatformOverrides, type AgentProcedure, type AgentRegistryEntry, type AgentRule, type AgentRuleBundle, type AgentRuleScope, type AgentSkill, type AgentSubAgent, type AgentSubAgentPlatformOverrides, type AgentTier, type AgentTierConfig, type AgentTierEntry, type AnalyzeTsDocCoverageOptions, type ApiDiffCheckOptions, type ApiDiffFinding, type ApiDiffResult, ApiExtractor, type ApiExtractorOptions, type ApiExtractorReportOptions, type ApiSurfaceEntry, type ApproveMergeUpgradeOptions, AstroConfig, type AstroConfigOptions, type AstroIntegrationSpec, AstroOutput, AstroProject, type AstroProjectOptions, AuditCategory, type AuditCheckRunner, type AuditCheckRunnerContext, type AuditFinding, type AuditFindingBase, type AuditLocation, AuditMode, type AuditReport, AuditSeverity, type AwsAccount, AwsCdkProject, type AwsCdkProjectOptions, AwsDeployWorkflow, AwsDeploymentConfig, AwsDeploymentTarget, type AwsDeploymentTargetOptions, type AwsLocalDeploymentConfig, type AwsOrganization, type AwsRegion, AwsTeardownWorkflow, type AwsTeardownWorkflowOptions, BUILT_IN_BUNDLES, BUNDLE_OWNERSHIP, type BundleOwnership, CLAUDE_RULE_TARGET, COMPLETE_JOB_ID, type CiDeploymentConfig, type ClassTypeOptions, type ClaudeAutoModeConfig, type ClaudeHookAction, type ClaudeHookEntry, type ClaudeHooksConfig, type ClaudeMdConfig, type ClaudePermissionsConfig, type ClaudeRuleTarget, type ClaudeSandboxConfig, type ClaudeSettingsConfig, type CompileFencedSamplesOptions, type CopilotHandoff, type CursorHookAction, type CursorHooksConfig, type CursorSettingsConfig, type CustomDocSection, DEFAULT_AC_THRESHOLDS, DEFAULT_AGENT_PATHS, DEFAULT_AGENT_TIERS, DEFAULT_API_EXTRACTOR_CONFIG_FILE, DEFAULT_API_EXTRACTOR_ENTRY_POINT, DEFAULT_API_EXTRACTOR_REPORT_FILENAME, DEFAULT_API_EXTRACTOR_REPORT_FOLDER, DEFAULT_AUDIT_REPORT_DIR, DEFAULT_BUNDLE_OVERRIDES, DEFAULT_DECOMPOSITION_TEMPLATE, DEFAULT_DISPATCH_MODEL, DEFAULT_DISPATCH_TO_HOUSEKEEPING_RATIO, DEFAULT_HOUSEKEEPING_MODEL, DEFAULT_ISSUE_PRIORITY, DEFAULT_ISSUE_STATUS, DEFAULT_ISSUE_TEMPLATES_BUNDLE_PATH_PATTERNS, DEFAULT_ISSUE_TEMPLATES_EMIT_CHECKER, DEFAULT_ISSUE_TEMPLATES_EMIT_STARTER, DEFAULT_ISSUE_TEMPLATES_ENABLED, DEFAULT_ISSUE_TEMPLATES_PATH, DEFAULT_ISSUE_TEMPLATES_REQUIRE_REFERENCE, DEFAULT_OFF_PEAK_CRON_EXAMPLE, DEFAULT_PARTIAL_UNBLOCK_COMMENT_TEMPLATE, DEFAULT_PRIORITY_LABELS, DEFAULT_PRODUCT_CONTEXT_PATH, DEFAULT_PROGRESS_FILES_ENABLED, DEFAULT_PROGRESS_FILES_FILENAME_PATTERN, DEFAULT_PROGRESS_FILES_FORMAT, DEFAULT_PROGRESS_FILES_STALE_AFTER_HOURS, DEFAULT_PROGRESS_FILES_STATE_DIR, DEFAULT_REQUIRE_PRODUCT_CONTEXT, DEFAULT_RESOLVED_ISSUE_DEFAULTS, DEFAULT_SAMPLE_COMPILER_OPTIONS, DEFAULT_SCHEDULED_TASKS_ROOT, DEFAULT_SCHEDULED_TASK_ENTRIES, DEFAULT_SHARED_EDITING_CONFLICT_STRATEGY, DEFAULT_SHARED_EDITING_EMIT_HELPER, DEFAULT_SHARED_EDITING_ENABLED, DEFAULT_SHARED_EDITING_VERIFY_COMMIT, DEFAULT_SHARED_INDEX_PATHS, DEFAULT_SKILL_EVALS_EMIT_RUNNER, DEFAULT_SKILL_EVALS_ENABLED, DEFAULT_SKILL_EVALS_SKILLS_ROOT, DEFAULT_SOURCES_THRESHOLDS, DEFAULT_STATE_FILE_PATH, DEFAULT_STATUS_LABELS, DEFAULT_TEARDOWN_BRANCH_PATTERNS, DEFAULT_TEMPORAL_FRAMING_CADENCES, DEFAULT_TEMPORAL_FRAMING_EMIT_CHECKER, DEFAULT_TEMPORAL_FRAMING_ENABLED, DEFAULT_TEMPORAL_FRAMING_PATHS, DEFAULT_TYPE_LABELS, DEFAULT_UNBLOCK_COMMENT_TEMPLATE, DEFAULT_UNBLOCK_DEPENDENTS_ENABLED, DEFAULT_UPSTREAM_CONFIGULATOR_ENABLED, DOCS_SYNC_AUDIT_SCHEMA_VERSION, type DeployWorkflowOptions, type DeploymentMetadata, type DocReferenceRecord, type EffectiveScopeThresholds, type ExtractDocReferencesOptions, type ExtractFencedSamplesOptions, type FencedSampleRecord, type FocusArea, type FocusAreaMatch, type FocusConfig, type GitBranch, type GitHubBoardMetadata, type GitHubProjectMetadata, type GitHubSprintMetadata, type IDependencyResolver, type IssueDefaultsConfig, type IssueDefaultsOverride, type IssueDefaultsPriority, type IssueDefaultsStatus, type IssueTemplatesConfig, JsiiFaker, LAYOUT_ENFORCEMENT, LAYOUT_ROOT_BY_PROJECT_TYPE, type LabelDefinition, type LayoutEnforcement, type LayoutViolation, type LinkFailureFinding, MAX_LABEL_DESCRIPTION_LENGTH, MCP_TRANSPORT, MERGE_METHODS, MIMIMUM_RELEASE_AGE, MINIMUM_RELEASE_AGE, MONOREPO_LAYOUT, type McpServerConfig, type McpTransport, type MeetingArea, type MeetingScope, type MeetingType, type MeetingTypeKind, type MeetingsConfig, type MergeMethod, type MonorepoLayoutRoot, MonorepoProject, type MonorepoProjectOptions, Nvmrc, type OrganizationMetadata, PROD_DEPLOY_NAME, PROGRESS_FILES_FORMAT_VALUES, PnpmWorkspace, type PnpmWorkspaceOptions, type PriorityRule, type ProgressFilesConfig, ProjectMetadata, type ProjectMetadataOptions, REQUIREMENTS_WRITER_PATHS, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, ReactViteSiteProject, type ReactViteSiteProjectOptions, type ReferenceMismatchCheckOptions, type ReferenceMismatchFinding, type RemoteCacheOptions, type RepositoryMetadata, ResetTask, type ResetTaskOptions, type ResolvedAgentPaths, type ResolvedAgentTier, type ResolvedIssueDefaults, type ResolvedIssueDefaultsEntry, type ResolvedIssueTemplates, type ResolvedProgressFiles, type ResolvedProjectMetadata, type ResolvedRunRatio, type ResolvedScheduledTask, type ResolvedScheduledTasks, type ResolvedScopeGate, type ResolvedScopeGateBundleOverride, type ResolvedSharedEditing, type ResolvedSkillEvals, type ResolvedTemporalFraming, type ResolvedUnblockDependents, type RunRatioConfig, type RunScanOptions, type RunScanResult, SCHEDULED_TASK_MODEL_VALUES, SCOPE_CLASS_VALUES, SHARED_EDITING_CONFLICT_STRATEGY_VALUES, STARLIGHT_ROLE, SUPPRESSED_WORKFLOW_RULE_NAMES, type SampleCompilationFailure, type SampleFailureFinding, SampleLang, type ScheduledTaskEntry, type ScheduledTaskModel, type ScheduledTaskOverride, type ScheduledTasksConfig, type ScopeClass, type ScopeGateBundleOverride, type ScopeGateConfig, type ScopeGateThresholds, type SharedEditingConfig, type SkillEvalsConfig, type SlackMetadata, type SourceTierExamples, type StarlightEditLink, type StarlightLogo, StarlightProject, type StarlightProjectOptions, type StarlightRole, type StarlightSidebarItem, type StarlightSingletonViolation, type StarlightSocialLink, type SyncLabelsOptions, TEMPORAL_FRAMING_CATEGORY_VALUES, type TemplateResolveResult, type TemporalFramingCategory, type TemporalFramingConfig, TestRunner, TsDocCoverageKind, type TsDocCoverageRecord, type TsdocCoverageCheckOptions, type TsdocCoverageFinding, TurboRepo, type TurboRepoOptions, TurboRepoTask, type TurboRepoTaskOptions, TypeScriptConfig, TypeScriptProject, type TypeScriptProjectOptions, UNKNOWN_TYPE_FALLBACK_TIER, type UnblockDependentsConfig, type UpstreamConfigulatorConfig, VALID_PRIORITY_VALUES, VALID_STATUS_VALUES, VERSION, VERSION_KEYS_SKIP, VERSION_NPM_PACKAGES, VSCodeConfig, type VersionKey, Vitest, type VitestConfigOptions, type VitestOptions, addApproveMergeUpgradeWorkflow, addBuildCompleteJob, addPlaywright, addStorybook, addSyncLabelsWorkflow, agendaBundle, analyzeTsDocCoverage, auditReportJsonSchema, awsCdkBundle, baseBundle, bcmWriterBundle, buildAgentRegistryRule, buildBaseBundle, buildBcmWriterBundle, buildBuiltInBundles, buildBusinessModelsBundle, buildCheckBlockedProcedure, buildCompanyProfileBundle, buildCustomerProfileBundle, buildDocsSyncBundle, buildIndustryDiscoveryBundle, buildMaintenanceAuditBundle, buildMeetingAnalysisBundle, buildOrchestratorConventionsContent, buildPeopleProfileBundle, buildRegulatoryResearchBundle, buildReport, buildRequirementsAnalystBundle, buildRequirementsReviewerBundle, buildRequirementsWriterBundle, buildResearchPipelineBundle, buildSoftwareProfileBundle, buildStandardsResearchBundle, buildUnblockDependentsProcedure, bundleNameForWorkflowRule, businessModelsBundle, checkDocSamplesProcedure, checkLinksProcedure, classifyIssueScope, classifyRun, companyProfileBundle, compileFencedSamples, createApiDiffCheck, createReferenceMismatchCheck, createTsdocCoverageCheck, customerProfileBundle, diffApiRollups, docsSyncBundle, emptyCategoryBuckets, extractApiProcedure, extractDocReferences, extractFencedSamples, formatLayoutViolation, formatStarlightSingletonViolation, getLatestEligibleVersion, githubWorkflowBundle, hasAnyDocsEmittingBundle, hasAnyDownstreamIssueKindBundle, industryDiscoveryBundle, isPhaseLabelOwnedByExcluded, isScheduledTaskOwnedByExcluded, isSuppressedWorkflowRule, isTypeLabelOwnedByExcluded, jestBundle, labelsForPhase, maintenanceAuditBundle, meetingAnalysisBundle, orchestratorBundle, parseApiRollup, peopleProfileBundle, persistAuditReport, pinPnpmActionSetup, pinSetupNodeVersion, pnpmBundle, prReviewBundle, projenBundle, referenceRecordToFinding, regulatoryResearchBundle, renderAgentTierCaseStatement, renderAgentTierSection, renderCheckDocSamplesProcedure, renderCheckLinksProcedure, renderCustomDocSectionBlock, renderCustomDocSections, renderExtractApiProcedure, renderFocusSection, renderIssueTemplatesBundleHook, renderIssueTemplatesCheckerScript, renderIssueTemplatesRuleContent, renderIssueTemplatesStarterPage, renderMeetingTypesSection, renderPriorityRulesSection, renderProgressFileName, renderProgressFilePath, renderProgressFilesBundleHook, renderProgressFilesRuleContent, renderRunRatioSection, renderRunRatioShellHelpers, renderScheduledTaskSkillFile, renderScheduledTasksSection, renderScopeGateSection, renderScopeGateShellHelpers, renderSharedEditingBundleHook, renderSharedEditingHelperScript, renderSharedEditingRuleContent, renderSkillEvalsBundleHook, renderSkillEvalsRuleContent, renderSkillEvalsRunnerScript, renderSourceTierExamples, renderStubIndexConventionRuleContent, renderTemporalFramingCheckerScript, renderTemporalFramingRuleContent, renderUnblockDependentsScript, renderUnblockDependentsSection, requirementsAnalystBundle, requirementsReviewerBundle, requirementsWriterBundle, researchPipelineBundle, resolveAgentPaths, resolveAgentTiers, resolveAstroProjectOutdir, resolveAwsCdkProjectOutdir, resolveIssueDefaults, resolveIssueTemplates, resolveModelAlias, resolveOrchestratorAssets, resolveOutdirFromPackageName, resolveOverrideForLabels, resolveProgressFiles, resolveReactViteSiteProjectOutdir, resolveRunRatio, resolveScheduledTasks, resolveScopeGate, resolveSharedEditing, resolveSkillEvals, resolveTemplateVariables, resolveTemporalFraming, resolveTypeScriptProjectOutdir, resolveUnblockDependents, runScan, slackBundle, softwareProfileBundle, standardsResearchBundle, tsdocRecordToFindings, turborepoBundle, typescriptBundle, upstreamConfigulatorDocsBundle, validateAgentTierConfig, validateIssueDefaultsConfig, validateIssueTemplatesConfig, validateMonorepoLayout, validateProgressFilesConfig, validateRunRatioConfig, validateScheduledTasksConfig, validateScopeGateConfig, validateSharedEditingConfig, validateSkillEvalsConfig, validateStarlightSingleton, validateTemporalFramingConfig, validateUnblockDependentsConfig, vitestBundle };

package/lib/index.d.ts

@@ -9568,6 +9568,29 @@ interface RemoteCacheOptions {
      */
     readonly teamName: string;
 }
+/**
+ * Options for {@link TurboRepo.activateBranchNameEnvVar}.
+ *
+ * The `tasks` field is required so callers explicitly name every task whose
+ * cache hash should include `GIT_BRANCH_NAME`. Scoping the env to a small
+ * set of consuming tasks (typically CDK `synth` / `package`) preserves
+ * cross-branch cache hits for every other task in the monorepo — library
+ * `compile` / `test` / `lint` / `package` runs no longer miss cache just
+ * because the branch name changed.
+ */
+interface ActivateBranchNameEnvVarOptions {
+    /**
+     * Tasks whose cache hash should include GIT_BRANCH_NAME. Each named task
+     * gets the env added to its `env: []` array. Unknown task names throw at
+     * synth time so typos surface immediately.
+     *
+     * Adding a task to this list is a deliberate cache-hit-rate tradeoff:
+     * the task will miss cache on every branch switch. Only name tasks that
+     * actually read `GIT_BRANCH_NAME` at runtime (e.g. CDK stack-name
+     * generators that bake the branch into resource names).
+     */
+    readonly tasks: Array<string>;
+}
 interface TurboRepoOptions {
     /**
      * Version of turborepo to use.
@@ -9908,11 +9931,24 @@ declare class TurboRepo extends Component$1 {
      */
     addGlobalEnvVar(name: string, value: string): void;
     /**
-     * Sets GIT_BRANCH_NAME so root tasks (e.g. build:all) pass the current branch.
-     * Value must be exactly $(...) so Projen's task runtime expands it; the shell
-     * then expands ${GIT_BRANCH_NAME:-$(git rev-parse --abbrev-ref HEAD)}.
+     * @deprecated Pass `{ tasks: [...] }` and name only the tasks whose cache
+     * hash must include `GIT_BRANCH_NAME`. The no-args form writes the env to
+     * the root `globalEnv` array, which forces every task in the monorepo to
+     * miss cache on every branch switch — destroying cross-branch cache hits
+     * for library `compile` / `test` / `lint` / `package` work that does not
+     * read the branch name at runtime.
      */
     activateBranchNameEnvVar(): void;
+    /**
+     * Scopes `GIT_BRANCH_NAME` to the named tasks on this TurboRepo. The env
+     * is written to each task's `env: []` array so only those tasks miss
+     * cache on a branch switch. Other tasks (and the root `globalEnv`) are
+     * left untouched.
+     *
+     * Throws at synth time when `options.tasks` contains a name that does
+     * not match a task on this TurboRepo, so typos surface immediately.
+     */
+    activateBranchNameEnvVar(options: ActivateBranchNameEnvVarOptions): void;
     preSynthesize(): void;
 }
 
@@ -10718,4 +10754,4 @@ declare function pinPnpmActionSetup(project: Project): void;
 declare function pinSetupNodeVersion(project: Project): void;
 
 export { AGENT_MODEL, AGENT_PLATFORM, AGENT_REGISTRY_ENTRIES, AGENT_RULE_SCOPE, AGENT_TIER_ROLES, AGENT_TIER_VALUES, AUDIT_CATEGORY_ORDER, AgentConfig, ApiExtractor, AstroConfig, AstroOutput, AstroProject, AuditCategory, AuditMode, AuditSeverity, AwsCdkProject, AwsDeployWorkflow, AwsDeploymentConfig, AwsDeploymentTarget, AwsTeardownWorkflow, BUILT_IN_BUNDLES, BUNDLE_OWNERSHIP, CLAUDE_RULE_TARGET, COMPLETE_JOB_ID, DEFAULT_AC_THRESHOLDS, DEFAULT_AGENT_PATHS, DEFAULT_AGENT_TIERS, DEFAULT_API_EXTRACTOR_CONFIG_FILE, DEFAULT_API_EXTRACTOR_ENTRY_POINT, DEFAULT_API_EXTRACTOR_REPORT_FILENAME, DEFAULT_API_EXTRACTOR_REPORT_FOLDER, DEFAULT_AUDIT_REPORT_DIR, DEFAULT_BUNDLE_OVERRIDES, DEFAULT_DECOMPOSITION_TEMPLATE, DEFAULT_DISPATCH_MODEL, DEFAULT_DISPATCH_TO_HOUSEKEEPING_RATIO, DEFAULT_HOUSEKEEPING_MODEL, DEFAULT_ISSUE_PRIORITY, DEFAULT_ISSUE_STATUS, DEFAULT_ISSUE_TEMPLATES_BUNDLE_PATH_PATTERNS, DEFAULT_ISSUE_TEMPLATES_EMIT_CHECKER, DEFAULT_ISSUE_TEMPLATES_EMIT_STARTER, DEFAULT_ISSUE_TEMPLATES_ENABLED, DEFAULT_ISSUE_TEMPLATES_PATH, DEFAULT_ISSUE_TEMPLATES_REQUIRE_REFERENCE, DEFAULT_OFF_PEAK_CRON_EXAMPLE, DEFAULT_PARTIAL_UNBLOCK_COMMENT_TEMPLATE, DEFAULT_PRIORITY_LABELS, DEFAULT_PRODUCT_CONTEXT_PATH, DEFAULT_PROGRESS_FILES_ENABLED, DEFAULT_PROGRESS_FILES_FILENAME_PATTERN, DEFAULT_PROGRESS_FILES_FORMAT, DEFAULT_PROGRESS_FILES_STALE_AFTER_HOURS, DEFAULT_PROGRESS_FILES_STATE_DIR, DEFAULT_REQUIRE_PRODUCT_CONTEXT, DEFAULT_RESOLVED_ISSUE_DEFAULTS, DEFAULT_SAMPLE_COMPILER_OPTIONS, DEFAULT_SCHEDULED_TASKS_ROOT, DEFAULT_SCHEDULED_TASK_ENTRIES, DEFAULT_SHARED_EDITING_CONFLICT_STRATEGY, DEFAULT_SHARED_EDITING_EMIT_HELPER, DEFAULT_SHARED_EDITING_ENABLED, DEFAULT_SHARED_EDITING_VERIFY_COMMIT, DEFAULT_SHARED_INDEX_PATHS, DEFAULT_SKILL_EVALS_EMIT_RUNNER, DEFAULT_SKILL_EVALS_ENABLED, DEFAULT_SKILL_EVALS_SKILLS_ROOT, DEFAULT_SOURCES_THRESHOLDS, DEFAULT_STATE_FILE_PATH, DEFAULT_STATUS_LABELS, DEFAULT_TEARDOWN_BRANCH_PATTERNS, DEFAULT_TEMPORAL_FRAMING_CADENCES, DEFAULT_TEMPORAL_FRAMING_EMIT_CHECKER, DEFAULT_TEMPORAL_FRAMING_ENABLED, DEFAULT_TEMPORAL_FRAMING_PATHS, DEFAULT_TYPE_LABELS, DEFAULT_UNBLOCK_COMMENT_TEMPLATE, DEFAULT_UNBLOCK_DEPENDENTS_ENABLED, DEFAULT_UPSTREAM_CONFIGULATOR_ENABLED, DOCS_SYNC_AUDIT_SCHEMA_VERSION, JsiiFaker, LAYOUT_ENFORCEMENT, LAYOUT_ROOT_BY_PROJECT_TYPE, MAX_LABEL_DESCRIPTION_LENGTH, MCP_TRANSPORT, MERGE_METHODS, MIMIMUM_RELEASE_AGE, MINIMUM_RELEASE_AGE, MONOREPO_LAYOUT, MonorepoProject, Nvmrc, PROD_DEPLOY_NAME, PROGRESS_FILES_FORMAT_VALUES, PnpmWorkspace, ProjectMetadata, REQUIREMENTS_WRITER_PATHS, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, ReactViteSiteProject, ResetTask, SCHEDULED_TASK_MODEL_VALUES, SCOPE_CLASS_VALUES, SHARED_EDITING_CONFLICT_STRATEGY_VALUES, STARLIGHT_ROLE, SUPPRESSED_WORKFLOW_RULE_NAMES, SampleLang, StarlightProject, TEMPORAL_FRAMING_CATEGORY_VALUES, TestRunner, TsDocCoverageKind, TurboRepo, TurboRepoTask, TypeScriptConfig, TypeScriptProject, UNKNOWN_TYPE_FALLBACK_TIER, VALID_PRIORITY_VALUES, VALID_STATUS_VALUES, VERSION, VERSION_KEYS_SKIP, VERSION_NPM_PACKAGES, VSCodeConfig, Vitest, addApproveMergeUpgradeWorkflow, addBuildCompleteJob, addPlaywright, addStorybook, addSyncLabelsWorkflow, agendaBundle, analyzeTsDocCoverage, auditReportJsonSchema, awsCdkBundle, baseBundle, bcmWriterBundle, buildAgentRegistryRule, buildBaseBundle, buildBcmWriterBundle, buildBuiltInBundles, buildBusinessModelsBundle, buildCheckBlockedProcedure, buildCompanyProfileBundle, buildCustomerProfileBundle, buildDocsSyncBundle, buildIndustryDiscoveryBundle, buildMaintenanceAuditBundle, buildMeetingAnalysisBundle, buildOrchestratorConventionsContent, buildPeopleProfileBundle, buildRegulatoryResearchBundle, buildReport, buildRequirementsAnalystBundle, buildRequirementsReviewerBundle, buildRequirementsWriterBundle, buildResearchPipelineBundle, buildSoftwareProfileBundle, buildStandardsResearchBundle, buildUnblockDependentsProcedure, bundleNameForWorkflowRule, businessModelsBundle, checkDocSamplesProcedure, checkLinksProcedure, classifyIssueScope, classifyRun, companyProfileBundle, compileFencedSamples, createApiDiffCheck, createReferenceMismatchCheck, createTsdocCoverageCheck, customerProfileBundle, diffApiRollups, docsSyncBundle, emptyCategoryBuckets, extractApiProcedure, extractDocReferences, extractFencedSamples, formatLayoutViolation, formatStarlightSingletonViolation, getLatestEligibleVersion, githubWorkflowBundle, hasAnyDocsEmittingBundle, hasAnyDownstreamIssueKindBundle, industryDiscoveryBundle, isPhaseLabelOwnedByExcluded, isScheduledTaskOwnedByExcluded, isSuppressedWorkflowRule, isTypeLabelOwnedByExcluded, jestBundle, labelsForPhase, maintenanceAuditBundle, meetingAnalysisBundle, orchestratorBundle, parseApiRollup, peopleProfileBundle, persistAuditReport, pinPnpmActionSetup, pinSetupNodeVersion, pnpmBundle, prReviewBundle, projenBundle, referenceRecordToFinding, regulatoryResearchBundle, renderAgentTierCaseStatement, renderAgentTierSection, renderCheckDocSamplesProcedure, renderCheckLinksProcedure, renderCustomDocSectionBlock, renderCustomDocSections, renderExtractApiProcedure, renderFocusSection, renderIssueTemplatesBundleHook, renderIssueTemplatesCheckerScript, renderIssueTemplatesRuleContent, renderIssueTemplatesStarterPage, renderMeetingTypesSection, renderPriorityRulesSection, renderProgressFileName, renderProgressFilePath, renderProgressFilesBundleHook, renderProgressFilesRuleContent, renderRunRatioSection, renderRunRatioShellHelpers, renderScheduledTaskSkillFile, renderScheduledTasksSection, renderScopeGateSection, renderScopeGateShellHelpers, renderSharedEditingBundleHook, renderSharedEditingHelperScript, renderSharedEditingRuleContent, renderSkillEvalsBundleHook, renderSkillEvalsRuleContent, renderSkillEvalsRunnerScript, renderSourceTierExamples, renderStubIndexConventionRuleContent, renderTemporalFramingCheckerScript, renderTemporalFramingRuleContent, renderUnblockDependentsScript, renderUnblockDependentsSection, requirementsAnalystBundle, requirementsReviewerBundle, requirementsWriterBundle, researchPipelineBundle, resolveAgentPaths, resolveAgentTiers, resolveAstroProjectOutdir, resolveAwsCdkProjectOutdir, resolveIssueDefaults, resolveIssueTemplates, resolveModelAlias, resolveOrchestratorAssets, resolveOutdirFromPackageName, resolveOverrideForLabels, resolveProgressFiles, resolveReactViteSiteProjectOutdir, resolveRunRatio, resolveScheduledTasks, resolveScopeGate, resolveSharedEditing, resolveSkillEvals, resolveTemplateVariables, resolveTemporalFraming, resolveTypeScriptProjectOutdir, resolveUnblockDependents, runScan, slackBundle, softwareProfileBundle, standardsResearchBundle, tsdocRecordToFindings, turborepoBundle, typescriptBundle, upstreamConfigulatorDocsBundle, validateAgentTierConfig, validateIssueDefaultsConfig, validateIssueTemplatesConfig, validateMonorepoLayout, validateProgressFilesConfig, validateRunRatioConfig, validateScheduledTasksConfig, validateScopeGateConfig, validateSharedEditingConfig, validateSkillEvalsConfig, validateStarlightSingleton, validateTemporalFramingConfig, validateUnblockDependentsConfig, vitestBundle };
-export type { AddStorybookOptions, AgentCommand, AgentConfigOptions, AgentExpansionRules, AgentFeaturesConfig, AgentModel, AgentPathsConfig, AgentPlatform, AgentPlatformOverrides, AgentProcedure, AgentRegistryEntry, AgentRule, AgentRuleBundle, AgentRuleScope, AgentSkill, AgentSubAgent, AgentSubAgentPlatformOverrides, AgentTier, AgentTierConfig, AgentTierEntry, AnalyzeTsDocCoverageOptions, ApiDiffCheckOptions, ApiDiffFinding, ApiDiffResult, ApiExtractorOptions, ApiExtractorReportOptions, ApiSurfaceEntry, ApproveMergeUpgradeOptions, AstroConfigOptions, AstroIntegrationSpec, AstroProjectOptions, AuditCheckRunner, AuditCheckRunnerContext, AuditFinding, AuditFindingBase, AuditLocation, AuditReport, AwsAccount, AwsCdkProjectOptions, AwsDeploymentTargetOptions, AwsLocalDeploymentConfig, AwsOrganization, AwsRegion, AwsTeardownWorkflowOptions, BundleOwnership, CiDeploymentConfig, ClassTypeOptions, ClaudeAutoModeConfig, ClaudeHookAction, ClaudeHookEntry, ClaudeHooksConfig, ClaudeMdConfig, ClaudePermissionsConfig, ClaudeRuleTarget, ClaudeSandboxConfig, ClaudeSettingsConfig, CompileFencedSamplesOptions, CopilotHandoff, CursorHookAction, CursorHooksConfig, CursorSettingsConfig, CustomDocSection, DeployWorkflowOptions, DeploymentMetadata, DocReferenceRecord, EffectiveScopeThresholds, ExtractDocReferencesOptions, ExtractFencedSamplesOptions, FencedSampleRecord, FocusArea, FocusAreaMatch, FocusConfig, GitBranch, GitHubBoardMetadata, GitHubProjectMetadata, GitHubSprintMetadata, IDependencyResolver, IssueDefaultsConfig, IssueDefaultsOverride, IssueDefaultsPriority, IssueDefaultsStatus, IssueTemplatesConfig, LabelDefinition, LayoutEnforcement, LayoutViolation, LinkFailureFinding, McpServerConfig, McpTransport, MeetingArea, MeetingScope, MeetingType, MeetingTypeKind, MeetingsConfig, MergeMethod, MonorepoLayoutRoot, MonorepoProjectOptions, OrganizationMetadata, PnpmWorkspaceOptions, PriorityRule, ProgressFilesConfig, ProjectMetadataOptions, ReactViteSiteProjectOptions, ReferenceMismatchCheckOptions, ReferenceMismatchFinding, RemoteCacheOptions, RepositoryMetadata, ResetTaskOptions, ResolvedAgentPaths, ResolvedAgentTier, ResolvedIssueDefaults, ResolvedIssueDefaultsEntry, ResolvedIssueTemplates, ResolvedProgressFiles, ResolvedProjectMetadata, ResolvedRunRatio, ResolvedScheduledTask, ResolvedScheduledTasks, ResolvedScopeGate, ResolvedScopeGateBundleOverride, ResolvedSharedEditing, ResolvedSkillEvals, ResolvedTemporalFraming, ResolvedUnblockDependents, RunRatioConfig, RunScanOptions, RunScanResult, SampleCompilationFailure, SampleFailureFinding, ScheduledTaskEntry, ScheduledTaskModel, ScheduledTaskOverride, ScheduledTasksConfig, ScopeClass, ScopeGateBundleOverride, ScopeGateConfig, ScopeGateThresholds, SharedEditingConfig, SkillEvalsConfig, SlackMetadata, SourceTierExamples, StarlightEditLink, StarlightLogo, StarlightProjectOptions, StarlightRole, StarlightSidebarItem, StarlightSingletonViolation, StarlightSocialLink, SyncLabelsOptions, TemplateResolveResult, TemporalFramingCategory, TemporalFramingConfig, TsDocCoverageRecord, TsdocCoverageCheckOptions, TsdocCoverageFinding, TurboRepoOptions, TurboRepoTaskOptions, TypeScriptProjectOptions, UnblockDependentsConfig, UpstreamConfigulatorConfig, VersionKey, VitestConfigOptions, VitestOptions };
+export type { ActivateBranchNameEnvVarOptions, AddStorybookOptions, AgentCommand, AgentConfigOptions, AgentExpansionRules, AgentFeaturesConfig, AgentModel, AgentPathsConfig, AgentPlatform, AgentPlatformOverrides, AgentProcedure, AgentRegistryEntry, AgentRule, AgentRuleBundle, AgentRuleScope, AgentSkill, AgentSubAgent, AgentSubAgentPlatformOverrides, AgentTier, AgentTierConfig, AgentTierEntry, AnalyzeTsDocCoverageOptions, ApiDiffCheckOptions, ApiDiffFinding, ApiDiffResult, ApiExtractorOptions, ApiExtractorReportOptions, ApiSurfaceEntry, ApproveMergeUpgradeOptions, AstroConfigOptions, AstroIntegrationSpec, AstroProjectOptions, AuditCheckRunner, AuditCheckRunnerContext, AuditFinding, AuditFindingBase, AuditLocation, AuditReport, AwsAccount, AwsCdkProjectOptions, AwsDeploymentTargetOptions, AwsLocalDeploymentConfig, AwsOrganization, AwsRegion, AwsTeardownWorkflowOptions, BundleOwnership, CiDeploymentConfig, ClassTypeOptions, ClaudeAutoModeConfig, ClaudeHookAction, ClaudeHookEntry, ClaudeHooksConfig, ClaudeMdConfig, ClaudePermissionsConfig, ClaudeRuleTarget, ClaudeSandboxConfig, ClaudeSettingsConfig, CompileFencedSamplesOptions, CopilotHandoff, CursorHookAction, CursorHooksConfig, CursorSettingsConfig, CustomDocSection, DeployWorkflowOptions, DeploymentMetadata, DocReferenceRecord, EffectiveScopeThresholds, ExtractDocReferencesOptions, ExtractFencedSamplesOptions, FencedSampleRecord, FocusArea, FocusAreaMatch, FocusConfig, GitBranch, GitHubBoardMetadata, GitHubProjectMetadata, GitHubSprintMetadata, IDependencyResolver, IssueDefaultsConfig, IssueDefaultsOverride, IssueDefaultsPriority, IssueDefaultsStatus, IssueTemplatesConfig, LabelDefinition, LayoutEnforcement, LayoutViolation, LinkFailureFinding, McpServerConfig, McpTransport, MeetingArea, MeetingScope, MeetingType, MeetingTypeKind, MeetingsConfig, MergeMethod, MonorepoLayoutRoot, MonorepoProjectOptions, OrganizationMetadata, PnpmWorkspaceOptions, PriorityRule, ProgressFilesConfig, ProjectMetadataOptions, ReactViteSiteProjectOptions, ReferenceMismatchCheckOptions, ReferenceMismatchFinding, RemoteCacheOptions, RepositoryMetadata, ResetTaskOptions, ResolvedAgentPaths, ResolvedAgentTier, ResolvedIssueDefaults, ResolvedIssueDefaultsEntry, ResolvedIssueTemplates, ResolvedProgressFiles, ResolvedProjectMetadata, ResolvedRunRatio, ResolvedScheduledTask, ResolvedScheduledTasks, ResolvedScopeGate, ResolvedScopeGateBundleOverride, ResolvedSharedEditing, ResolvedSkillEvals, ResolvedTemporalFraming, ResolvedUnblockDependents, RunRatioConfig, RunScanOptions, RunScanResult, SampleCompilationFailure, SampleFailureFinding, ScheduledTaskEntry, ScheduledTaskModel, ScheduledTaskOverride, ScheduledTasksConfig, ScopeClass, ScopeGateBundleOverride, ScopeGateConfig, ScopeGateThresholds, SharedEditingConfig, SkillEvalsConfig, SlackMetadata, SourceTierExamples, StarlightEditLink, StarlightLogo, StarlightProjectOptions, StarlightRole, StarlightSidebarItem, StarlightSingletonViolation, StarlightSocialLink, SyncLabelsOptions, TemplateResolveResult, TemporalFramingCategory, TemporalFramingConfig, TsDocCoverageRecord, TsdocCoverageCheckOptions, TsdocCoverageFinding, TurboRepoOptions, TurboRepoTaskOptions, TypeScriptProjectOptions, UnblockDependentsConfig, UpstreamConfigulatorConfig, VersionKey, VitestConfigOptions, VitestOptions };

package/lib/index.js

@@ -27868,16 +27868,32 @@ var _TurboRepo = class _TurboRepo extends import_lib2.Component {
       this.globalEnv.push(name);
     }
   }
-  /**
-   * Sets GIT_BRANCH_NAME so root tasks (e.g. build:all) pass the current branch.
-   * Value must be exactly $(...) so Projen's task runtime expands it; the shell
-   * then expands ${GIT_BRANCH_NAME:-$(git rev-parse --abbrev-ref HEAD)}.
-   */
-  activateBranchNameEnvVar() {
-    this.addGlobalEnvVar(
-      "GIT_BRANCH_NAME",
-      '$(echo "${GIT_BRANCH_NAME:-$(git rev-parse --abbrev-ref HEAD)}")'
+  activateBranchNameEnvVar(options) {
+    const value = '$(echo "${GIT_BRANCH_NAME:-$(git rev-parse --abbrev-ref HEAD)}")';
+    if (options === void 0) {
+      this.project.logger.warn(
+        "TurboRepo.activateBranchNameEnvVar() with no arguments is deprecated. It writes GIT_BRANCH_NAME to the root `globalEnv`, which forces every task in the monorepo to miss cache on every branch switch. Pass `{ tasks: [...] }` and name only the tasks that actually consume the branch (e.g. CDK synth/package) to preserve cross-branch cache hits for everything else."
+      );
+      this.addGlobalEnvVar("GIT_BRANCH_NAME", value);
+      return;
+    }
+    const knownTaskNames = this.tasks.map((task) => task.name);
+    const unknown = options.tasks.filter(
+      (name) => !knownTaskNames.includes(name)
     );
+    if (unknown.length > 0) {
+      throw new Error(
+        `TurboRepo.activateBranchNameEnvVar: unknown task name(s) ${JSON.stringify(
+          unknown
+        )}. Known tasks on this TurboRepo: ${JSON.stringify(knownTaskNames)}.`
+      );
+    }
+    for (const name of options.tasks) {
+      const task = this.tasks.find((t) => t.name === name);
+      if (task && !task.env.includes("GIT_BRANCH_NAME")) {
+        task.env.push("GIT_BRANCH_NAME");
+      }
+    }
   }
   preSynthesize() {
     let nextDependsOn = this.project.deps.all.filter((d) => d.version === "workspace:*").map((d) => [d.name, ROOT_TURBO_TASK_NAME].join("#"));