@codedrifters/configulator 0.0.255 → 0.0.256

package/lib/index.d.mts

@@ -970,6 +970,156 @@ interface PriorityRule {
      */
     readonly rationale: string;
 }
+/*******************************************************************************
+ *
+ * Focus Scoring
+ *
+ ******************************************************************************/
+/**
+ * Match predicate for a single focus area. At least one sub-field
+ * should be set; multiple sub-fields on the same match combine as a
+ * logical OR (any one matching contributes the focus area's weight).
+ *
+ * @see FocusArea
+ */
+interface FocusAreaMatch {
+    /** Any of these labels present on the issue matches. */
+    readonly labels?: ReadonlyArray<string>;
+    /**
+     * Case-insensitive substrings matched against the issue title.
+     * A hit on any single keyword fires the match.
+     */
+    readonly titleKeywords?: ReadonlyArray<string>;
+    /**
+     * Case-insensitive substrings matched against the issue body.
+     * A hit on any single keyword fires the match.
+     */
+    readonly bodyKeywords?: ReadonlyArray<string>;
+}
+/**
+ * A single scored focus area — a named customer, segment,
+ * organization, software product, regulation, or person the project
+ * cares about right now. Matching issues receive this area's
+ * `weight` as a priority boost at triage time.
+ *
+ * @see FocusConfig
+ * @see ./bundles/focus.ts#renderFocusSection
+ */
+interface FocusArea {
+    /** Human-readable name for the focus area (e.g. "Acme Corp"). */
+    readonly name: string;
+    /**
+     * Consuming-repo-defined vocabulary describing what kind of entity
+     * this focus area represents (e.g. `"customer"`, `"segment"`,
+     * `"organization"`, `"software"`, `"regulation"`, `"person"`).
+     * The `AgentExpansionRules.allowedTypes` /
+     * `AgentExpansionRules.forbiddenTypes` lists gate what values
+     * agents are permitted to introduce.
+     */
+    readonly type: string;
+    /**
+     * Provenance. `"human"` entries are curated by a maintainer;
+     * `"agent"` entries were appended by an agent under the
+     * agent-expansion rules and must carry a `discoveredIn` reference.
+     */
+    readonly source: "human" | "agent";
+    /**
+     * Issue reference (e.g. `"#123"`) that introduced the focus area.
+     * Required when `source` is `"agent"` so the provenance of every
+     * agent-appended entry is auditable; optional for human entries.
+     */
+    readonly discoveredIn?: string;
+    /** Match predicate that decides which issues this area applies to. */
+    readonly match: FocusAreaMatch;
+    /**
+     * Positive integer weight contributed to the issue's focus score
+     * when the match fires. Consuming repos typically cap this with
+     * `AgentExpansionRules.maxWeight` (default 8 in openhi's reference
+     * implementation).
+     */
+    readonly weight: number;
+}
+/**
+ * Guard-rails on what agents are allowed to append to `focus.json`
+ * without human review. The agent-expansion contract is append-only:
+ * agents never modify or remove existing entries.
+ */
+interface AgentExpansionRules {
+    /**
+     * Hard cap on the `weight` an agent may set on a newly appended
+     * focus area. Human curators may use higher weights.
+     */
+    readonly maxWeight: number;
+    /**
+     * Whitelist of `FocusArea.type` values agents are permitted to
+     * introduce. Any type outside this list must be added by a human.
+     */
+    readonly allowedTypes: ReadonlyArray<string>;
+    /**
+     * Explicit blocklist of `FocusArea.type` values agents must never
+     * introduce, even if the list accidentally overlaps
+     * `allowedTypes`. `forbiddenTypes` wins on conflict.
+     */
+    readonly forbiddenTypes: ReadonlyArray<string>;
+    /**
+     * Optional cap on the number of entries in each keyword array
+     * (`match.labels`, `match.titleKeywords`, `match.bodyKeywords`)
+     * on an agent-appended focus area. Prevents runaway keyword
+     * expansion. Human entries are not subject to this cap.
+     */
+    readonly maxKeywords?: number;
+}
+/**
+ * Top-level configuration for the focus-scoring engine. The schema
+ * and agent-expansion rules live in the configulator bundle; the
+ * actual `focus.json` file is authored and curated in the consuming
+ * repo.
+ *
+ * When supplied via `AgentConfigOptions.focus`, the `base` bundle
+ * appends a "Focus scoring" subsection to the
+ * `issue-label-conventions` rule that teaches agents how to read
+ * `focus.json`, how focus weight interacts with the
+ * `priority:*` taxonomy, and what they may and may not append to
+ * the file.
+ *
+ * @see FocusArea
+ * @see AgentExpansionRules
+ * @see ./bundles/focus.ts#renderFocusSection
+ */
+interface FocusConfig {
+    /**
+     * Path to the focus file relative to the repo root.
+     * @default ".claude/focus.json"
+     */
+    readonly focusFilePath?: string;
+    /**
+     * Schema version the consuming repo's `focus.json` conforms to.
+     * Bump when the schema changes in a backwards-incompatible way.
+     * @default 1
+     */
+    readonly schemaVersion?: number;
+    /**
+     * Cumulative focus-score thresholds that map into the
+     * `priority:*` taxonomy. An issue whose total focus score
+     * (sum of matched focus-area weights) reaches `high` is boosted
+     * to `priority:high`; reaching `medium` keeps it at
+     * `priority:medium`. Scores below `medium` do not affect the
+     * inferred priority.
+     *
+     * @remarks `high` and `medium` must be integers. The JSON schema
+     * at `schemas/focus.schema.json` enforces this for `focus.json`.
+     */
+    readonly thresholds?: {
+        readonly high: number;
+        readonly medium: number;
+    };
+    /**
+     * Guard-rails that govern what agents may append to `focus.json`.
+     * When omitted, the rendered rule documents that agents must
+     * **not** append to `focus.json` without human review.
+     */
+    readonly agentExpansionRules?: AgentExpansionRules;
+}
 /*******************************************************************************
  *
  * AgentConfig Options
@@ -1082,6 +1232,26 @@ interface AgentConfigOptions {
      * @see ./bundles/priority-rules.ts#renderPriorityRulesSection
      */
     readonly priorityRules?: ReadonlyArray<PriorityRule>;
+    /**
+     * Focus-scoring configuration. Declares the path to the consuming
+     * repo's `focus.json` file, score thresholds, and the
+     * agent-expansion rules that govern what agents may append to the
+     * file.
+     *
+     * When set, the `base` bundle appends a "Focus scoring"
+     * subsection to the `issue-label-conventions` rule that teaches
+     * agents (a) how to read `focus.json`, (b) how focus weight
+     * interacts with the `priority:*` taxonomy, and (c) the
+     * agent-driven expansion contract. The actual `focus.json` file
+     * is authored and curated in the consuming repo — configulator
+     * ships the schema and agent instructions only.
+     *
+     * @see FocusConfig
+     * @see FocusArea
+     * @see AgentExpansionRules
+     * @see ./bundles/focus.ts#renderFocusSection
+     */
+    readonly focus?: FocusConfig;
 }
 
 /**
@@ -1354,6 +1524,24 @@ declare const prReviewBundle: AgentRuleBundle;
  */
 declare const projenBundle: AgentRuleBundle;
 
+/**
+ * Render the markdown subsection appended to the
+ * `issue-label-conventions` rule when `AgentConfigOptions.focus` is
+ * supplied. Returns an empty string when `focus` is undefined so
+ * callers can unconditionally concatenate the result.
+ *
+ * The section documents three things for agents:
+ *
+ * 1. How to read `focus.json` at triage time
+ * 2. How focus weight interacts with the `priority:*` taxonomy
+ * 3. The agent-driven expansion contract (what agents may append)
+ *
+ * Configulator ships this rule content plus a JSON Schema that
+ * validates the `focus.json` file; the file itself is authored and
+ * curated in the consuming repo.
+ */
+declare function renderFocusSection(focus: FocusConfig | undefined): string;
+
 /**
  * Render the markdown subsection appended to the
  * `issue-label-conventions` rule when `AgentConfigOptions.priorityRules`
@@ -4088,4 +4276,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 AgentPathsConfig, 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_AGENT_PATHS, 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, type PriorityRule, ProjectMetadata, type ProjectMetadataOptions, REQUIREMENTS_WRITER_PATHS, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, type RemoteCacheOptions, type RepositoryMetadata, ResetTask, type ResetTaskOptions, type ResolvedAgentPaths, type ResolvedProjectMetadata, STARLIGHT_ROLE, type SlackMetadata, type StarlightEditLink, type StarlightLogo, StarlightProject, type StarlightProjectOptions, type StarlightRole, type StarlightSidebarItem, type StarlightSingletonViolation, 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, formatStarlightSingletonViolation, getLatestEligibleVersion, githubWorkflowBundle, industryDiscoveryBundle, jestBundle, maintenanceAuditBundle, meetingAnalysisBundle, orchestratorBundle, peopleProfileBundle, pnpmBundle, prReviewBundle, projenBundle, renderPriorityRulesSection, requirementsAnalystBundle, requirementsReviewerBundle, requirementsWriterBundle, researchPipelineBundle, resolveAgentPaths, resolveAstroProjectOutdir, resolveAwsCdkProjectOutdir, resolveModelAlias, resolveOutdirFromPackageName, resolveTemplateVariables, resolveTypeScriptProjectOutdir, slackBundle, softwareProfileBundle, turborepoBundle, typescriptBundle, validateMonorepoLayout, validateStarlightSingleton, vitestBundle };
+export { AGENT_MODEL, AGENT_PLATFORM, AGENT_RULE_SCOPE, AgentConfig, type AgentConfigOptions, type AgentExpansionRules, type AgentModel, type AgentPathsConfig, 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_AGENT_PATHS, DEFAULT_PRIORITY_LABELS, DEFAULT_STATUS_LABELS, DEFAULT_TEARDOWN_BRANCH_PATTERNS, DEFAULT_TYPE_LABELS, type DeployWorkflowOptions, type DeploymentMetadata, type FocusArea, type FocusAreaMatch, type FocusConfig, 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, type PriorityRule, ProjectMetadata, type ProjectMetadataOptions, REQUIREMENTS_WRITER_PATHS, ROOT_CI_TASK_NAME, ROOT_TURBO_TASK_NAME, type RemoteCacheOptions, type RepositoryMetadata, ResetTask, type ResetTaskOptions, type ResolvedAgentPaths, type ResolvedProjectMetadata, STARLIGHT_ROLE, type SlackMetadata, type StarlightEditLink, type StarlightLogo, StarlightProject, type StarlightProjectOptions, type StarlightRole, type StarlightSidebarItem, type StarlightSingletonViolation, 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, formatStarlightSingletonViolation, getLatestEligibleVersion, githubWorkflowBundle, industryDiscoveryBundle, jestBundle, maintenanceAuditBundle, meetingAnalysisBundle, orchestratorBundle, peopleProfileBundle, pnpmBundle, prReviewBundle, projenBundle, renderFocusSection, renderPriorityRulesSection, requirementsAnalystBundle, requirementsReviewerBundle, requirementsWriterBundle, researchPipelineBundle, resolveAgentPaths, resolveAstroProjectOutdir, resolveAwsCdkProjectOutdir, resolveModelAlias, resolveOutdirFromPackageName, resolveTemplateVariables, resolveTypeScriptProjectOutdir, slackBundle, softwareProfileBundle, turborepoBundle, typescriptBundle, validateMonorepoLayout, validateStarlightSingleton, vitestBundle };

package/lib/index.d.ts

@@ -1019,6 +1019,156 @@ interface PriorityRule {
      */
     readonly rationale: string;
 }
+/*******************************************************************************
+ *
+ * Focus Scoring
+ *
+ ******************************************************************************/
+/**
+ * Match predicate for a single focus area. At least one sub-field
+ * should be set; multiple sub-fields on the same match combine as a
+ * logical OR (any one matching contributes the focus area's weight).
+ *
+ * @see FocusArea
+ */
+interface FocusAreaMatch {
+    /** Any of these labels present on the issue matches. */
+    readonly labels?: ReadonlyArray<string>;
+    /**
+     * Case-insensitive substrings matched against the issue title.
+     * A hit on any single keyword fires the match.
+     */
+    readonly titleKeywords?: ReadonlyArray<string>;
+    /**
+     * Case-insensitive substrings matched against the issue body.
+     * A hit on any single keyword fires the match.
+     */
+    readonly bodyKeywords?: ReadonlyArray<string>;
+}
+/**
+ * A single scored focus area — a named customer, segment,
+ * organization, software product, regulation, or person the project
+ * cares about right now. Matching issues receive this area's
+ * `weight` as a priority boost at triage time.
+ *
+ * @see FocusConfig
+ * @see ./bundles/focus.ts#renderFocusSection
+ */
+interface FocusArea {
+    /** Human-readable name for the focus area (e.g. "Acme Corp"). */
+    readonly name: string;
+    /**
+     * Consuming-repo-defined vocabulary describing what kind of entity
+     * this focus area represents (e.g. `"customer"`, `"segment"`,
+     * `"organization"`, `"software"`, `"regulation"`, `"person"`).
+     * The `AgentExpansionRules.allowedTypes` /
+     * `AgentExpansionRules.forbiddenTypes` lists gate what values
+     * agents are permitted to introduce.
+     */
+    readonly type: string;
+    /**
+     * Provenance. `"human"` entries are curated by a maintainer;
+     * `"agent"` entries were appended by an agent under the
+     * agent-expansion rules and must carry a `discoveredIn` reference.
+     */
+    readonly source: "human" | "agent";
+    /**
+     * Issue reference (e.g. `"#123"`) that introduced the focus area.
+     * Required when `source` is `"agent"` so the provenance of every
+     * agent-appended entry is auditable; optional for human entries.
+     */
+    readonly discoveredIn?: string;
+    /** Match predicate that decides which issues this area applies to. */
+    readonly match: FocusAreaMatch;
+    /**
+     * Positive integer weight contributed to the issue's focus score
+     * when the match fires. Consuming repos typically cap this with
+     * `AgentExpansionRules.maxWeight` (default 8 in openhi's reference
+     * implementation).
+     */
+    readonly weight: number;
+}
+/**
+ * Guard-rails on what agents are allowed to append to `focus.json`
+ * without human review. The agent-expansion contract is append-only:
+ * agents never modify or remove existing entries.
+ */
+interface AgentExpansionRules {
+    /**
+     * Hard cap on the `weight` an agent may set on a newly appended
+     * focus area. Human curators may use higher weights.
+     */
+    readonly maxWeight: number;
+    /**
+     * Whitelist of `FocusArea.type` values agents are permitted to
+     * introduce. Any type outside this list must be added by a human.
+     */
+    readonly allowedTypes: ReadonlyArray<string>;
+    /**
+     * Explicit blocklist of `FocusArea.type` values agents must never
+     * introduce, even if the list accidentally overlaps
+     * `allowedTypes`. `forbiddenTypes` wins on conflict.
+     */
+    readonly forbiddenTypes: ReadonlyArray<string>;
+    /**
+     * Optional cap on the number of entries in each keyword array
+     * (`match.labels`, `match.titleKeywords`, `match.bodyKeywords`)
+     * on an agent-appended focus area. Prevents runaway keyword
+     * expansion. Human entries are not subject to this cap.
+     */
+    readonly maxKeywords?: number;
+}
+/**
+ * Top-level configuration for the focus-scoring engine. The schema
+ * and agent-expansion rules live in the configulator bundle; the
+ * actual `focus.json` file is authored and curated in the consuming
+ * repo.
+ *
+ * When supplied via `AgentConfigOptions.focus`, the `base` bundle
+ * appends a "Focus scoring" subsection to the
+ * `issue-label-conventions` rule that teaches agents how to read
+ * `focus.json`, how focus weight interacts with the
+ * `priority:*` taxonomy, and what they may and may not append to
+ * the file.
+ *
+ * @see FocusArea
+ * @see AgentExpansionRules
+ * @see ./bundles/focus.ts#renderFocusSection
+ */
+interface FocusConfig {
+    /**
+     * Path to the focus file relative to the repo root.
+     * @default ".claude/focus.json"
+     */
+    readonly focusFilePath?: string;
+    /**
+     * Schema version the consuming repo's `focus.json` conforms to.
+     * Bump when the schema changes in a backwards-incompatible way.
+     * @default 1
+     */
+    readonly schemaVersion?: number;
+    /**
+     * Cumulative focus-score thresholds that map into the
+     * `priority:*` taxonomy. An issue whose total focus score
+     * (sum of matched focus-area weights) reaches `high` is boosted
+     * to `priority:high`; reaching `medium` keeps it at
+     * `priority:medium`. Scores below `medium` do not affect the
+     * inferred priority.
+     *
+     * @remarks `high` and `medium` must be integers. The JSON schema
+     * at `schemas/focus.schema.json` enforces this for `focus.json`.
+     */
+    readonly thresholds?: {
+        readonly high: number;
+        readonly medium: number;
+    };
+    /**
+     * Guard-rails that govern what agents may append to `focus.json`.
+     * When omitted, the rendered rule documents that agents must
+     * **not** append to `focus.json` without human review.
+     */
+    readonly agentExpansionRules?: AgentExpansionRules;
+}
 /*******************************************************************************
  *
  * AgentConfig Options
@@ -1131,6 +1281,26 @@ interface AgentConfigOptions {
      * @see ./bundles/priority-rules.ts#renderPriorityRulesSection
      */
     readonly priorityRules?: ReadonlyArray<PriorityRule>;
+    /**
+     * Focus-scoring configuration. Declares the path to the consuming
+     * repo's `focus.json` file, score thresholds, and the
+     * agent-expansion rules that govern what agents may append to the
+     * file.
+     *
+     * When set, the `base` bundle appends a "Focus scoring"
+     * subsection to the `issue-label-conventions` rule that teaches
+     * agents (a) how to read `focus.json`, (b) how focus weight
+     * interacts with the `priority:*` taxonomy, and (c) the
+     * agent-driven expansion contract. The actual `focus.json` file
+     * is authored and curated in the consuming repo — configulator
+     * ships the schema and agent instructions only.
+     *
+     * @see FocusConfig
+     * @see FocusArea
+     * @see AgentExpansionRules
+     * @see ./bundles/focus.ts#renderFocusSection
+     */
+    readonly focus?: FocusConfig;
 }
 
 /**
@@ -1403,6 +1573,24 @@ declare const prReviewBundle: AgentRuleBundle;
  */
 declare const projenBundle: AgentRuleBundle;
 
+/**
+ * Render the markdown subsection appended to the
+ * `issue-label-conventions` rule when `AgentConfigOptions.focus` is
+ * supplied. Returns an empty string when `focus` is undefined so
+ * callers can unconditionally concatenate the result.
+ *
+ * The section documents three things for agents:
+ *
+ * 1. How to read `focus.json` at triage time
+ * 2. How focus weight interacts with the `priority:*` taxonomy
+ * 3. The agent-driven expansion contract (what agents may append)
+ *
+ * Configulator ships this rule content plus a JSON Schema that
+ * validates the `focus.json` file; the file itself is authored and
+ * curated in the consuming repo.
+ */
+declare function renderFocusSection(focus: FocusConfig | undefined): string;
+
 /**
  * Render the markdown subsection appended to the
  * `issue-label-conventions` rule when `AgentConfigOptions.priorityRules`
@@ -4137,5 +4325,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_AGENT_PATHS, 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, STARLIGHT_ROLE, StarlightProject, TestRunner, TurboRepo, TurboRepoTask, TypeScriptConfig, TypeScriptProject, VERSION, VERSION_KEYS_SKIP, VERSION_NPM_PACKAGES, VSCodeConfig, Vitest, addApproveMergeUpgradeWorkflow, addBuildCompleteJob, addSyncLabelsWorkflow, awsCdkBundle, baseBundle, bcmWriterBundle, companyProfileBundle, formatLayoutViolation, formatStarlightSingletonViolation, getLatestEligibleVersion, githubWorkflowBundle, industryDiscoveryBundle, jestBundle, maintenanceAuditBundle, meetingAnalysisBundle, orchestratorBundle, peopleProfileBundle, pnpmBundle, prReviewBundle, projenBundle, renderPriorityRulesSection, requirementsAnalystBundle, requirementsReviewerBundle, requirementsWriterBundle, researchPipelineBundle, resolveAgentPaths, resolveAstroProjectOutdir, resolveAwsCdkProjectOutdir, resolveModelAlias, resolveOutdirFromPackageName, resolveTemplateVariables, resolveTypeScriptProjectOutdir, slackBundle, softwareProfileBundle, turborepoBundle, typescriptBundle, validateMonorepoLayout, validateStarlightSingleton, vitestBundle };
-export type { AgentConfigOptions, AgentModel, AgentPathsConfig, 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, PriorityRule, ProjectMetadataOptions, RemoteCacheOptions, RepositoryMetadata, ResetTaskOptions, ResolvedAgentPaths, ResolvedProjectMetadata, SlackMetadata, StarlightEditLink, StarlightLogo, StarlightProjectOptions, StarlightRole, StarlightSidebarItem, StarlightSingletonViolation, 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_AGENT_PATHS, 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, STARLIGHT_ROLE, StarlightProject, TestRunner, TurboRepo, TurboRepoTask, TypeScriptConfig, TypeScriptProject, VERSION, VERSION_KEYS_SKIP, VERSION_NPM_PACKAGES, VSCodeConfig, Vitest, addApproveMergeUpgradeWorkflow, addBuildCompleteJob, addSyncLabelsWorkflow, awsCdkBundle, baseBundle, bcmWriterBundle, companyProfileBundle, formatLayoutViolation, formatStarlightSingletonViolation, getLatestEligibleVersion, githubWorkflowBundle, industryDiscoveryBundle, jestBundle, maintenanceAuditBundle, meetingAnalysisBundle, orchestratorBundle, peopleProfileBundle, pnpmBundle, prReviewBundle, projenBundle, renderFocusSection, renderPriorityRulesSection, requirementsAnalystBundle, requirementsReviewerBundle, requirementsWriterBundle, researchPipelineBundle, resolveAgentPaths, resolveAstroProjectOutdir, resolveAwsCdkProjectOutdir, resolveModelAlias, resolveOutdirFromPackageName, resolveTemplateVariables, resolveTypeScriptProjectOutdir, slackBundle, softwareProfileBundle, turborepoBundle, typescriptBundle, validateMonorepoLayout, validateStarlightSingleton, vitestBundle };
+export type { AgentConfigOptions, AgentExpansionRules, AgentModel, AgentPathsConfig, 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, FocusArea, FocusAreaMatch, FocusConfig, GitBranch, GitHubBoardMetadata, GitHubProjectMetadata, GitHubSprintMetadata, IDependencyResolver, LabelDefinition, LayoutEnforcement, LayoutViolation, McpServerConfig, McpTransport, MergeMethod, MonorepoLayoutRoot, MonorepoProjectOptions, OrganizationMetadata, PnpmWorkspaceOptions, PriorityRule, ProjectMetadataOptions, RemoteCacheOptions, RepositoryMetadata, ResetTaskOptions, ResolvedAgentPaths, ResolvedProjectMetadata, SlackMetadata, StarlightEditLink, StarlightLogo, StarlightProjectOptions, StarlightRole, StarlightSidebarItem, StarlightSingletonViolation, StarlightSocialLink, SyncLabelsOptions, TemplateResolveResult, TurboRepoOptions, TurboRepoTaskOptions, TypeScriptProjectOptions, VersionKey, VitestConfigOptions, VitestOptions };

package/lib/index.js

@@ -243,6 +243,7 @@ __export(index_exports, {
   pnpmBundle: () => pnpmBundle,
   prReviewBundle: () => prReviewBundle,
   projenBundle: () => projenBundle,
+  renderFocusSection: () => renderFocusSection,
   renderPriorityRulesSection: () => renderPriorityRulesSection,
   requirementsAnalystBundle: () => requirementsAnalystBundle,
   requirementsReviewerBundle: () => requirementsReviewerBundle,
@@ -14581,6 +14582,126 @@ var vitestBundle = {
   }
 };
 
+// src/agent/bundles/focus.ts
+var DEFAULT_FOCUS_FILE_PATH = ".claude/focus.json";
+var DEFAULT_SCHEMA_VERSION = 1;
+function renderFocusSection(focus) {
+  if (!focus) {
+    return "";
+  }
+  const focusFilePath = focus.focusFilePath ?? DEFAULT_FOCUS_FILE_PATH;
+  const schemaVersion = focus.schemaVersion ?? DEFAULT_SCHEMA_VERSION;
+  const lines = [
+    "## Focus scoring",
+    "",
+    "This project runs a **focus-scoring engine** alongside the generic",
+    "`priority:*` inference above. Focus scoring boosts the priority of",
+    "issues that match the project's currently-declared focus areas \u2014",
+    "named customers, segments, organizations, software products,",
+    "regulations, or people the project cares about right now.",
+    "",
+    "### Reading `focus.json`",
+    "",
+    `The focus file lives at \`${focusFilePath}\` and conforms to schema`,
+    `version \`${schemaVersion}\`. Each entry declares a match predicate`,
+    "(any combination of `labels`, `titleKeywords`, `bodyKeywords`) and",
+    "a positive integer `weight`. At triage time:",
+    "",
+    `1. Read \`${focusFilePath}\`. If the file is missing or empty,`,
+    "   skip focus scoring entirely \u2014 the generic priority heuristics",
+    "   apply unchanged.",
+    "2. For each focus area, test its match predicate against the",
+    "   issue's labels, title, and body. A match on **any** sub-field",
+    "   (labels / title keywords / body keywords) fires the area and",
+    "   contributes its `weight` to the issue's focus score.",
+    "3. Keyword matching is case-insensitive substring matching \u2014",
+    '   `titleKeywords: ["Acme"]` matches an issue titled',
+    "   `feat: onboard acme corp`.",
+    "4. Sum all matched weights to produce the issue's **focus score**.",
+    ""
+  ];
+  lines.push("### How focus score interacts with `priority:*`");
+  lines.push("");
+  if (focus.thresholds) {
+    const { high, medium } = focus.thresholds;
+    lines.push(`A focus score of \`${high}\` or more boosts the`);
+    const mediumBand = high - medium === 1 ? `A focus score of \`${medium}\` keeps` : `A focus score of \`${medium}\` up to \`${high - 1}\` keeps`;
+    lines.push(
+      "issue to `priority:high`.",
+      `${mediumBand} the issue at \`priority:medium\`. Scores below`,
+      `\`${medium}\` do **not** alter the priority that`,
+      "the generic heuristics would otherwise infer."
+    );
+  } else {
+    lines.push(
+      "This project has not declared explicit focus-score thresholds.",
+      "Treat any non-zero focus score as a soft signal to lift one",
+      "priority tier (never above `priority:high`) unless the generic",
+      "heuristics already pin a higher tier."
+    );
+  }
+  lines.push("");
+  lines.push(
+    "Focus scoring **never lowers** an issue's priority \u2014 the generic",
+    "heuristics set the floor, and focus weight can only lift it.",
+    "`priority:critical` is never set by focus scoring alone; the",
+    "generic heuristics own that tier."
+  );
+  lines.push("");
+  lines.push("### Agent-driven expansion");
+  lines.push("");
+  if (focus.agentExpansionRules) {
+    const rules = focus.agentExpansionRules;
+    const allowedList = rules.allowedTypes.map((t) => `\`${t}\``).join(", ");
+    const forbiddenList = rules.forbiddenTypes.map((t) => `\`${t}\``).join(", ");
+    lines.push(
+      `Agents may **append** new focus areas to \`${focusFilePath}\``,
+      "when they discover a relevant entity during work, subject to",
+      "these guard-rails:"
+    );
+    lines.push("");
+    lines.push(
+      `- **Max weight.** Agent-appended entries must set \`weight\` to`,
+      `  \`${rules.maxWeight}\` or less. Higher weights require a human.`
+    );
+    lines.push(
+      "- **Allowed types.** Agents may only introduce entries whose",
+      `  \`type\` is one of: ${allowedList || "(none)"}.`
+    );
+    if (rules.forbiddenTypes.length > 0) {
+      lines.push(
+        "- **Forbidden types.** Even inside `allowedTypes`, agents must",
+        `  never introduce entries whose \`type\` is one of: ${forbiddenList}.`
+      );
+    }
+    if (rules.maxKeywords !== void 0) {
+      lines.push(
+        "- **Max keywords per match field.** Agent-appended entries",
+        `  may list at most \`${rules.maxKeywords}\` items in each of`,
+        "  `match.labels`, `match.titleKeywords`, and `match.bodyKeywords`."
+      );
+    }
+    lines.push(
+      '- **Provenance.** Agent-appended entries must set `source: "agent"`',
+      '  and `discoveredIn: "#<issue>"` referencing the issue that',
+      "  surfaced the focus area."
+    );
+    lines.push(
+      "- **Append-only.** Never modify or remove existing entries.",
+      "  Human curators own edits and deletions."
+    );
+  } else {
+    lines.push(
+      `Agents must **not** append to \`${focusFilePath}\`. This project`,
+      "has not declared agent-expansion rules \u2014 all focus-area curation",
+      "is performed by humans. If you discover a relevant entity that",
+      "is not covered by an existing focus area, raise it in the issue",
+      "or PR discussion instead of editing the focus file."
+    );
+  }
+  return lines.join("\n");
+}
+
 // src/agent/bundles/priority-rules.ts
 function renderPriorityRulesSection(rules) {
   if (rules.length === 0) {
@@ -15554,6 +15675,22 @@ ${section}`
         });
       }
     }
+    if (this.options.focus) {
+      const issueLabelRule = ruleMap.get("issue-label-conventions");
+      if (issueLabelRule) {
+        const section = renderFocusSection(this.options.focus);
+        if (section.length > 0) {
+          ruleMap.set("issue-label-conventions", {
+            ...issueLabelRule,
+            content: `${issueLabelRule.content}
+
+---
+
+${section}`
+          });
+        }
+      }
+    }
     return [...ruleMap.values()].sort((a, b) => {
       if (a.name === "project-overview") return -1;
       if (b.name === "project-overview") return 1;
@@ -18365,6 +18502,7 @@ var TypeScriptConfig = class extends import_projen22.Component {
   pnpmBundle,
   prReviewBundle,
   projenBundle,
+  renderFocusSection,
   renderPriorityRulesSection,
   requirementsAnalystBundle,
   requirementsReviewerBundle,