@codedrifters/configulator 0.0.191 → 0.0.192

package/docs/label-taxonomy.md

@@ -0,0 +1,138 @@
+# Label Taxonomy Ownership
+
+Configulator synthesizes a canonical GitHub label set for every consuming
+project via the sync-labels workflow. This document defines **who owns
+which label families** so the taxonomy stays coherent as more agent
+bundles are ported.
+
+## Three ownership tiers
+
+Labels fall into one of three tiers based on who is responsible for
+defining them, maintaining their colors and descriptions, and keeping
+them in sync with the agent rules that depend on them.
+
+### Tier 1 — Configulator core labels
+
+Defined statically in `src/workflows/sync-labels.ts` and applied to
+every project that uses `addSyncLabelsWorkflow`. These are the labels
+that the orchestrator, issue-worker, and PR automation depend on
+regardless of which specific agent bundles a project enables.
+
+Families in this tier:
+
+- **`status:*`** — workflow state (`ready`, `in-progress`, `blocked`,
+  `done`, `deferred`, `needs-attention`). Required by every agent that
+  transitions issues through the workflow.
+- **`priority:*`** — scheduling priority (`critical`, `high`, `medium`,
+  `low`, `trivial`). Required by the orchestrator to sequence work.
+- **`type:*`** — conventional-commit work type (`feat`, `fix`, `docs`,
+  `chore`, `refactor`, `style`, `perf`, `test`, `build`, `ci`,
+  `revert`, `release`, `hotfix`). Matches the PR title convention so
+  automation can derive one from the other.
+
+These are exported as `DEFAULT_STATUS_LABELS`, `DEFAULT_PRIORITY_LABELS`,
+and `DEFAULT_TYPE_LABELS` and are always merged in.
+
+### Tier 2 — Agent-bundle labels
+
+Owned by the individual agent bundle that depends on them. A bundle
+should contribute only the labels its rules reference — typically a
+small family of phase labels used by a multi-phase workflow.
+
+Examples seen in the vortex reference taxonomy:
+
+- `meeting:extract`, `meeting:notes`, `meeting:draft`, `meeting:link`
+  — owned by the meeting-analysis bundle
+- `research:scope`, `research:search`, `research:synthesize`,
+  `research:verify` — owned by a research-pipeline bundle
+- `bcm:outline`, `bcm:scaffold`, `bcm:context`, `bcm:connect` —
+  owned by a bcm-writer bundle
+
+Bundle-contributed labels are scoped: a project that does not enable
+the meeting-analysis bundle does not get `meeting:*` labels. This
+keeps the label list per-project aligned with the workflows that
+project actually runs.
+
+A bundle declares its labels via the optional `labels` field on the
+`AgentRuleBundle` interface. When `AgentConfig` is enabled on a
+project, `addSyncLabelsWorkflow` merges labels from every active
+bundle into `.github/labels.yml` automatically.
+
+```ts
+export const meetingAnalysisBundle: AgentRuleBundle = {
+  name: "meeting-analysis",
+  // ...
+  labels: [
+    { name: "meeting:extract", color: "C5DEF5", description: "..." },
+    { name: "meeting:notes",   color: "BFDADC", description: "..." },
+    { name: "meeting:draft",   color: "D4C5F9", description: "..." },
+    { name: "meeting:link",    color: "FEF2C0", description: "..." },
+  ],
+};
+```
+
+Consumers can still override a bundle-contributed label's color or
+description by supplying the same label name via
+`SyncLabelsOptions.labels` — the consumer entry wins.
+
+### Tier 3 — Consumer-project labels
+
+Owned by the end project. These are domain-specific categories
+configulator cannot reasonably predict. Examples from the vortex
+reference project:
+
+- `area:requirements`, `area:business-strategy`, `area:references`,
+  `area:product`, `area:architecture` — area labels tied to a
+  directory layout unique to that project
+
+Consumers add these through the `labels` option on
+`addSyncLabelsWorkflow` / `SyncLabelsOptions.labels`.
+
+## How the tiers compose
+
+At synth time, the final label set written to `.github/labels.yml` is:
+
+```
+DEFAULT_STATUS_LABELS
+  ∪ DEFAULT_PRIORITY_LABELS
+  ∪ DEFAULT_TYPE_LABELS
+  ∪ (labels contributed by enabled agent bundles)
+  ∪ (labels provided by the consumer via options)
+```
+
+The sync-labels workflow then reconciles this set against the live
+repo — creating missing labels, updating colors/descriptions, and
+(if `deleteOtherLabels` is true, the default) removing any label that
+is not in the file.
+
+## Naming conventions
+
+- Use lowercase, kebab-case label names.
+- Use a family prefix followed by a colon: `family:name` (e.g.
+  `status:ready`, `meeting:extract`).
+- Keep descriptions short and action-oriented — they appear in the
+  GitHub UI dropdown when applying labels.
+- Pick distinct hex colors within a family so labels are scannable in
+  the issue list. Related families (e.g. all `research:*`) should
+  share a color gradient.
+
+## When to add a new label family
+
+Before adding a new family, check whether an existing one covers the
+intent:
+
+- Workflow state → `status:*`
+- Scheduling order → `priority:*`
+- Kind of change → `type:*`
+
+A new family is warranted when it cross-cuts the existing ones and
+is required by a specific agent's rules — for example, phase labels
+that track which micro-session of a multi-phase agent an issue
+belongs to.
+
+## See also
+
+- `docs/audits/label-audit-308.md` — initial audit of configulator
+  labels against the vortex reference taxonomy
+- `src/workflows/sync-labels.ts` — source of truth for the Tier 1
+  default labels

package/lib/index.d.mts

@@ -1,12 +1,12 @@
 import { Component, Project as Project$1, typescript } from 'projen';
 import { Project, Component as Component$1, Task } from 'projen/lib';
+import { NodeProject } from 'projen/lib/javascript';
 import { AwsCdkTypeScriptApp } from 'projen/lib/awscdk';
 import { AwsStageType, DeploymentTargetRoleType, AwsEnvironmentType, AWS_STAGE_TYPE } from '@codedrifters/utils';
 import * as spec from '@jsii/spec';
 import { TypeScriptProject as TypeScriptProject$1, TypeScriptAppProject, TypeScriptProjectOptions as TypeScriptProjectOptions$1 } from 'projen/lib/typescript';
 import { ValueOf } from 'type-fest';
 import { BuildWorkflowOptions, BuildWorkflow } from 'projen/lib/build';
-import { NodeProject } from 'projen/lib/javascript';
 import { JobStep } from 'projen/lib/github/workflows-model';
 
 /**
@@ -390,6 +390,56 @@ interface McpServerConfig {
     readonly disabledTools?: ReadonlyArray<string>;
 }
 
+/** A single GitHub label definition for EndBug/label-sync. */
+interface LabelDefinition {
+    /** Label name (e.g. "priority:high"). */
+    readonly name: string;
+    /** Hex color without the leading `#` (e.g. "B60205"). */
+    readonly color: string;
+    /** Short description shown in the GitHub UI. */
+    readonly description: string;
+}
+/** Options for the sync-labels workflow and labels config file. */
+interface SyncLabelsOptions {
+    /**
+     * Additional labels to sync alongside the standard defaults.
+     * Merged with DEFAULT_STATUS_LABELS, DEFAULT_PRIORITY_LABELS, and
+     * DEFAULT_TYPE_LABELS (standard labels are always included).
+     */
+    readonly labels?: ReadonlyArray<LabelDefinition>;
+    /**
+     * Remove labels from the repo that are not in the config file.
+     * @default true
+     */
+    readonly deleteOtherLabels?: boolean;
+    /**
+     * Workflow file name (display name in the Actions tab).
+     * @default "sync-labels"
+     */
+    readonly workflowName?: string;
+    /**
+     * Agent bundles whose contributed labels should be merged into
+     * `.github/labels.yml`. Typically populated by the project type from
+     * `AgentConfig.of(project)?.activeBundles` so bundle-supplied labels
+     * only appear when the bundle is actually enabled.
+     *
+     * Merge order: Tier 1 defaults → bundle labels → user-supplied `labels`
+     * (later entries override earlier ones on name collision).
+     */
+    readonly bundles?: ReadonlyArray<AgentRuleBundle>;
+}
+/** Default status labels. */
+declare const DEFAULT_STATUS_LABELS: ReadonlyArray<LabelDefinition>;
+/** Default priority labels. */
+declare const DEFAULT_PRIORITY_LABELS: ReadonlyArray<LabelDefinition>;
+/** Default type labels — one per conventional commit type. */
+declare const DEFAULT_TYPE_LABELS: ReadonlyArray<LabelDefinition>;
+/**
+ * Adds a labels config file and a GitHub Actions workflow that syncs
+ * labels to the repository using EndBug/label-sync.
+ */
+declare function addSyncLabelsWorkflow(project: NodeProject, options: SyncLabelsOptions): void;
+
 /*******************************************************************************
  *
  * Agent Rule Bundle
@@ -448,6 +498,15 @@ interface AgentRuleBundle {
         readonly allow?: ReadonlyArray<string>;
         readonly deny?: ReadonlyArray<string>;
     };
+    /**
+     * GitHub labels contributed by this bundle. When the bundle is active in a
+     * project that also uses the sync-labels workflow, these labels are merged
+     * into `.github/labels.yml` alongside the Tier 1 defaults.
+     *
+     * User-supplied labels (via `SyncLabelsOptions.labels`) override bundle
+     * labels on name collision.
+     */
+    readonly labels?: ReadonlyArray<LabelDefinition>;
 }
 /*******************************************************************************
  *
@@ -882,6 +941,15 @@ declare class AgentConfig extends Component {
     private static mergeClaudeDefaults;
     private readonly options;
     constructor(project: Project$1, options?: AgentConfigOptions);
+    /**
+     * Returns the bundles that are active for this project: auto-detected
+     * bundles (when `autoDetectBundles !== false`) plus force-included
+     * bundles, minus explicitly excluded bundles. Deduplicated by name.
+     *
+     * Exposed so sibling components (e.g. the sync-labels workflow) can
+     * consume bundle-contributed configuration.
+     */
+    get activeBundles(): ReadonlyArray<AgentRuleBundle>;
     preSynthesize(): void;
     private resolvePlatforms;
     private resolveRules;
@@ -2507,46 +2575,6 @@ interface ApproveMergeUpgradeOptions {
  */
 declare function addApproveMergeUpgradeWorkflow(project: NodeProject, options: ApproveMergeUpgradeOptions): void;
 
-/** A single GitHub label definition for EndBug/label-sync. */
-interface LabelDefinition {
-    /** Label name (e.g. "priority:high"). */
-    readonly name: string;
-    /** Hex color without the leading `#` (e.g. "B60205"). */
-    readonly color: string;
-    /** Short description shown in the GitHub UI. */
-    readonly description: string;
-}
-/** Options for the sync-labels workflow and labels config file. */
-interface SyncLabelsOptions {
-    /**
-     * Additional labels to sync alongside the standard defaults.
-     * Merged with DEFAULT_STATUS_LABELS, DEFAULT_PRIORITY_LABELS, and
-     * DEFAULT_TYPE_LABELS (standard labels are always included).
-     */
-    readonly labels?: ReadonlyArray<LabelDefinition>;
-    /**
-     * Remove labels from the repo that are not in the config file.
-     * @default true
-     */
-    readonly deleteOtherLabels?: boolean;
-    /**
-     * Workflow file name (display name in the Actions tab).
-     * @default "sync-labels"
-     */
-    readonly workflowName?: string;
-}
-/** Default status labels. */
-declare const DEFAULT_STATUS_LABELS: ReadonlyArray<LabelDefinition>;
-/** Default priority labels. */
-declare const DEFAULT_PRIORITY_LABELS: ReadonlyArray<LabelDefinition>;
-/** Default type labels — one per conventional commit type. */
-declare const DEFAULT_TYPE_LABELS: ReadonlyArray<LabelDefinition>;
-/**
- * Adds a labels config file and a GitHub Actions workflow that syncs
- * labels to the repository using EndBug/label-sync.
- */
-declare function addSyncLabelsWorkflow(project: NodeProject, options: SyncLabelsOptions): void;
-
 /*******************************************************************************
  *
  * Monorepo Root Project.

package/lib/index.d.ts

@@ -1,11 +1,11 @@
 import { Component, Project, typescript } from 'projen';
 import { Project as Project$1, Task, Component as Component$1 } from 'projen/lib';
+import { NodeProject } from 'projen/lib/javascript';
 import { AwsCdkTypeScriptApp } from 'projen/lib/awscdk';
 import * as spec from '@jsii/spec';
 import { TypeScriptProject as TypeScriptProject$1, TypeScriptAppProject, TypeScriptProjectOptions as TypeScriptProjectOptions$1 } from 'projen/lib/typescript';
 import { ValueOf } from 'type-fest';
 import { BuildWorkflow, BuildWorkflowOptions } from 'projen/lib/build';
-import { NodeProject } from 'projen/lib/javascript';
 import { JobStep } from 'projen/lib/github/workflows-model';
 
 /**
@@ -439,6 +439,56 @@ interface McpServerConfig {
     readonly disabledTools?: ReadonlyArray<string>;
 }
 
+/** A single GitHub label definition for EndBug/label-sync. */
+interface LabelDefinition {
+    /** Label name (e.g. "priority:high"). */
+    readonly name: string;
+    /** Hex color without the leading `#` (e.g. "B60205"). */
+    readonly color: string;
+    /** Short description shown in the GitHub UI. */
+    readonly description: string;
+}
+/** Options for the sync-labels workflow and labels config file. */
+interface SyncLabelsOptions {
+    /**
+     * Additional labels to sync alongside the standard defaults.
+     * Merged with DEFAULT_STATUS_LABELS, DEFAULT_PRIORITY_LABELS, and
+     * DEFAULT_TYPE_LABELS (standard labels are always included).
+     */
+    readonly labels?: ReadonlyArray<LabelDefinition>;
+    /**
+     * Remove labels from the repo that are not in the config file.
+     * @default true
+     */
+    readonly deleteOtherLabels?: boolean;
+    /**
+     * Workflow file name (display name in the Actions tab).
+     * @default "sync-labels"
+     */
+    readonly workflowName?: string;
+    /**
+     * Agent bundles whose contributed labels should be merged into
+     * `.github/labels.yml`. Typically populated by the project type from
+     * `AgentConfig.of(project)?.activeBundles` so bundle-supplied labels
+     * only appear when the bundle is actually enabled.
+     *
+     * Merge order: Tier 1 defaults → bundle labels → user-supplied `labels`
+     * (later entries override earlier ones on name collision).
+     */
+    readonly bundles?: ReadonlyArray<AgentRuleBundle>;
+}
+/** Default status labels. */
+declare const DEFAULT_STATUS_LABELS: ReadonlyArray<LabelDefinition>;
+/** Default priority labels. */
+declare const DEFAULT_PRIORITY_LABELS: ReadonlyArray<LabelDefinition>;
+/** Default type labels — one per conventional commit type. */
+declare const DEFAULT_TYPE_LABELS: ReadonlyArray<LabelDefinition>;
+/**
+ * Adds a labels config file and a GitHub Actions workflow that syncs
+ * labels to the repository using EndBug/label-sync.
+ */
+declare function addSyncLabelsWorkflow(project: NodeProject, options: SyncLabelsOptions): void;
+
 /*******************************************************************************
  *
  * Agent Rule Bundle
@@ -497,6 +547,15 @@ interface AgentRuleBundle {
         readonly allow?: ReadonlyArray<string>;
         readonly deny?: ReadonlyArray<string>;
     };
+    /**
+     * GitHub labels contributed by this bundle. When the bundle is active in a
+     * project that also uses the sync-labels workflow, these labels are merged
+     * into `.github/labels.yml` alongside the Tier 1 defaults.
+     *
+     * User-supplied labels (via `SyncLabelsOptions.labels`) override bundle
+     * labels on name collision.
+     */
+    readonly labels?: ReadonlyArray<LabelDefinition>;
 }
 /*******************************************************************************
  *
@@ -931,6 +990,15 @@ declare class AgentConfig extends Component {
     private static mergeClaudeDefaults;
     private readonly options;
     constructor(project: Project, options?: AgentConfigOptions);
+    /**
+     * Returns the bundles that are active for this project: auto-detected
+     * bundles (when `autoDetectBundles !== false`) plus force-included
+     * bundles, minus explicitly excluded bundles. Deduplicated by name.
+     *
+     * Exposed so sibling components (e.g. the sync-labels workflow) can
+     * consume bundle-contributed configuration.
+     */
+    get activeBundles(): ReadonlyArray<AgentRuleBundle>;
     preSynthesize(): void;
     private resolvePlatforms;
     private resolveRules;
@@ -2556,46 +2624,6 @@ interface ApproveMergeUpgradeOptions {
  */
 declare function addApproveMergeUpgradeWorkflow(project: NodeProject, options: ApproveMergeUpgradeOptions): void;
 
-/** A single GitHub label definition for EndBug/label-sync. */
-interface LabelDefinition {
-    /** Label name (e.g. "priority:high"). */
-    readonly name: string;
-    /** Hex color without the leading `#` (e.g. "B60205"). */
-    readonly color: string;
-    /** Short description shown in the GitHub UI. */
-    readonly description: string;
-}
-/** Options for the sync-labels workflow and labels config file. */
-interface SyncLabelsOptions {
-    /**
-     * Additional labels to sync alongside the standard defaults.
-     * Merged with DEFAULT_STATUS_LABELS, DEFAULT_PRIORITY_LABELS, and
-     * DEFAULT_TYPE_LABELS (standard labels are always included).
-     */
-    readonly labels?: ReadonlyArray<LabelDefinition>;
-    /**
-     * Remove labels from the repo that are not in the config file.
-     * @default true
-     */
-    readonly deleteOtherLabels?: boolean;
-    /**
-     * Workflow file name (display name in the Actions tab).
-     * @default "sync-labels"
-     */
-    readonly workflowName?: string;
-}
-/** Default status labels. */
-declare const DEFAULT_STATUS_LABELS: ReadonlyArray<LabelDefinition>;
-/** Default priority labels. */
-declare const DEFAULT_PRIORITY_LABELS: ReadonlyArray<LabelDefinition>;
-/** Default type labels — one per conventional commit type. */
-declare const DEFAULT_TYPE_LABELS: ReadonlyArray<LabelDefinition>;
-/**
- * Adds a labels config file and a GitHub Actions workflow that syncs
- * labels to the repository using EndBug/label-sync.
- */
-declare function addSyncLabelsWorkflow(project: NodeProject, options: SyncLabelsOptions): void;
-
 /*******************************************************************************
  *
  * Monorepo Root Project.

package/lib/index.js

@@ -1451,7 +1451,29 @@ var meetingAnalysisBundle = {
     }
   ],
   skills: [processMeetingSkill],
-  subAgents: [meetingAnalystSubAgent]
+  subAgents: [meetingAnalystSubAgent],
+  labels: [
+    {
+      name: "meeting:extract",
+      color: "C5DEF5",
+      description: "Phase 1: raw extraction from a meeting transcript"
+    },
+    {
+      name: "meeting:notes",
+      color: "BFDADC",
+      description: "Phase 2: curated notes derived from an extraction"
+    },
+    {
+      name: "meeting:draft",
+      color: "D4C5F9",
+      description: "Phase 3: draft follow-up issues proposed from notes"
+    },
+    {
+      name: "meeting:link",
+      color: "FEF2C0",
+      description: "Phase 4: linking/reconciling drafted issues with existing work"
+    }
+  ]
 };
 
 // src/agent/bundles/orchestrator.ts
@@ -4031,6 +4053,39 @@ var AgentConfig = class _AgentConfig extends import_projen8.Component {
     super(project);
     this.options = options;
   }
+  /**
+   * Returns the bundles that are active for this project: auto-detected
+   * bundles (when `autoDetectBundles !== false`) plus force-included
+   * bundles, minus explicitly excluded bundles. Deduplicated by name.
+   *
+   * Exposed so sibling components (e.g. the sync-labels workflow) can
+   * consume bundle-contributed configuration.
+   */
+  get activeBundles() {
+    const bundleMap = /* @__PURE__ */ new Map();
+    if (this.options.autoDetectBundles !== false) {
+      for (const bundle of BUILT_IN_BUNDLES) {
+        if (this.options.excludeBundles?.includes(bundle.name)) {
+          continue;
+        }
+        if (bundle.name === "base" && this.options.includeBaseRules === false) {
+          continue;
+        }
+        if (bundle.appliesWhen(this.project)) {
+          bundleMap.set(bundle.name, bundle);
+        }
+      }
+    }
+    if (this.options.includeBundles) {
+      for (const bundleName of this.options.includeBundles) {
+        const bundle = BUILT_IN_BUNDLES.find((b) => b.name === bundleName);
+        if (bundle) {
+          bundleMap.set(bundle.name, bundle);
+        }
+      }
+    }
+    return [...bundleMap.values()];
+  }
   preSynthesize() {
     super.preSynthesize();
     const platforms = this.resolvePlatforms();
@@ -5294,12 +5349,25 @@ var LABELS_CONFIG_PATH = ".github/labels.yml";
 function addSyncLabelsWorkflow(project, options) {
   const workflowName = options.workflowName ?? DEFAULT_WORKFLOW_NAME2;
   const deleteOtherLabels = options.deleteOtherLabels ?? true;
-  const allLabels = [
-    ...DEFAULT_STATUS_LABELS,
-    ...DEFAULT_PRIORITY_LABELS,
-    ...DEFAULT_TYPE_LABELS,
-    ...options.labels ?? []
-  ];
+  const labelMap = /* @__PURE__ */ new Map();
+  for (const label of DEFAULT_STATUS_LABELS) {
+    labelMap.set(label.name, label);
+  }
+  for (const label of DEFAULT_PRIORITY_LABELS) {
+    labelMap.set(label.name, label);
+  }
+  for (const label of DEFAULT_TYPE_LABELS) {
+    labelMap.set(label.name, label);
+  }
+  for (const bundle of options.bundles ?? []) {
+    for (const label of bundle.labels ?? []) {
+      labelMap.set(label.name, label);
+    }
+  }
+  for (const label of options.labels ?? []) {
+    labelMap.set(label.name, label);
+  }
+  const allLabels = [...labelMap.values()];
   new LabelsFile(project, allLabels);
   const workflow = project.github?.addWorkflow(workflowName);
   if (!workflow) {
@@ -5602,10 +5670,12 @@ var MonorepoProject = class extends import_typescript3.TypeScriptAppProject {
       );
     }
     if (options.syncLabels !== false) {
-      addSyncLabelsWorkflow(
-        this,
-        typeof options.syncLabels === "object" ? options.syncLabels : {}
-      );
+      const syncLabelsOptions = typeof options.syncLabels === "object" ? options.syncLabels : {};
+      const agentConfig = AgentConfig.of(this);
+      addSyncLabelsWorkflow(this, {
+        ...syncLabelsOptions,
+        bundles: syncLabelsOptions.bundles ?? agentConfig?.activeBundles
+      });
     }
     if (this.buildWorkflow) {
       addBuildCompleteJob(this.buildWorkflow);