@codedrifters/configulator 0.0.191 → 0.0.193

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