docs(framework): unify change taxonomy into one source of truth

.github/dependabot.yml

@@ -11,7 +11,6 @@ updates:
       include: "scope"
     labels:
       - "dependencies"
-      - "github-actions"
 
   - package-ecosystem: "npm"
     directory: "/"
@@ -24,4 +23,3 @@ updates:
       include: "scope"
     labels:
       - "dependencies"
-      - "npm"

.github/labels.yml

@@ -1,5 +1,9 @@
 # Canonical issue and PR label list for ai-driven-dev/framework.
 #
+# Labels are TRIAGE ONLY: they categorize an issue or PR. They never decide
+# where a PR targets — routing is by branch prefix (see aidd_docs/memory/vcs.md).
+# Keep one triage label per change.
+#
 # This file is the source of truth. When the GitHub label set drifts from
 # this file, sync manually with:
 #
@@ -24,31 +28,19 @@
   color: 0075ca
 
 - name: security
-  description: Security-sensitive issue or fix
+  description: Security-sensitive issue or fix (cross-cutting, add to any kind)
   color: B60205
 
 - name: good first issue
   description: Good for newcomers
   color: 7057ff
 
-- name: help wanted
-  description: Extra attention is needed
-  color: 008672
-
 # --- Dependencies --------------------------------------------------------
 
 - name: dependencies
   description: Dependency update (dependabot)
   color: 0366d6
 
-- name: github-actions
-  description: GitHub Actions workflow change
-  color: "000000"
-
-- name: npm
-  description: npm dependency update
-  color: cb3837
-
 # --- Release tooling -----------------------------------------------------
 
 - name: "autorelease: pending"

.github/workflows/back-merge.yml

@@ -25,7 +25,7 @@ jobs:
           app-id: ${{ secrets.AIDD_BOT_APP_ID }}
           private-key: ${{ secrets.AIDD_BOT_PRIVATE_KEY }}
 
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           ref: next
           fetch-depth: 0

.github/workflows/ci.yml

@@ -22,7 +22,7 @@ jobs:
       contents: read
       pull-requests: read
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         with:
           fetch-depth: 0
       - uses: wagoid/commitlint-github-action@b948419dd99f3fd78a6548d48f94e3df7f6bf3ed # v6.2.1
@@ -94,7 +94,7 @@ jobs:
     if: needs.release-please.outputs.release_created == 'true'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Build clean marketplace bundle
         # A self-contained marketplace a user can extract and register with
@@ -141,7 +141,7 @@ jobs:
           - { tool: codex, mode: flat, flag: "--flat" }
           - { tool: opencode, mode: flat, flag: "--flat" }
     steps:
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
@@ -193,7 +193,7 @@ jobs:
             echo "released=false" >> $GITHUB_OUTPUT
           fi
 
-      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
         if: steps.check.outputs.released == 'true'
 
       - name: Get plugin version

.github/workflows/codeql.yml

@@ -28,7 +28,7 @@ jobs:
         language: [javascript-typescript]
     steps:
       - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Initialize CodeQL
         uses: github/codeql-action/init@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2

.github/workflows/validate.yml

@@ -22,7 +22,7 @@ jobs:
       CI: "true"
     steps:
       - name: Checkout
-        uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Setup Node
         uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0

CONTRIBUTING.md

@@ -68,16 +68,9 @@ One scope per commit (split cross-plugin changes). The types, the scopes, and th
 
 ## 3. Open a pull request
 
-- Branch off `next` and target `next` (the integration branch); `hotfix/*` branches off `main` for urgent production fixes. See [`RELEASE.md`](./RELEASE.md).
+- Branch off `next` and target `next` (the integration branch); only `hotfix/*` branches off `main` for urgent production fixes. The branch prefix alone decides the target — the full prefix → label → target table is in [`aidd_docs/memory/vcs.md`](aidd_docs/memory/vcs.md#types).
 - **Fill the PR template** (applied automatically): explain *what* changed and *how* you resolved it technically - that narrative is the point of the PR. The conventional title and pre-commit hooks are already enforced by CI, so don't spend the description re-asserting them.
-- **Label the PR** so reviewers and the [Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8) triage at a glance:
-
-  | Label | When to use |
-  | ----- | ----------- |
-  | `bug` | A fix for broken behaviour. |
-  | `enhancement` | A new skill, agent, rule, or feature. |
-  | `documentation` | A docs-only change (README, CONTRIBUTING, skill docs). |
-  | `security` | A security-sensitive change or fix. |
+- **Label the PR** so reviewers and the [Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8) triage at a glance. The triage label follows your branch kind and the PR skill applies it automatically; the label per kind is in that same [routing table](aidd_docs/memory/vcs.md#types) (`security` is cross-cutting — add it to any kind).
 - The PR title follows the same conventional format (the **Commitlint** CI job enforces it); PRs are squash-merged using that title.
 - A **Habilité** review gates every merge ([`CODEOWNERS`](./.github/CODEOWNERS)); Certifié contributors cannot self-merge.
 - Decision rules (lazy consensus, explicit consensus for cross-plugin/contract changes, the quality veto) live in [`GOVERNANCE.md`](./GOVERNANCE.md#code-decisions-merging).

RELEASE.md

@@ -21,7 +21,9 @@ For who may merge and release, see [`GOVERNANCE.md`](GOVERNANCE.md).
 ## Where your change goes
 
 Almost everything flows through `next` and ships in the weekly release. Only an
-urgent production fix takes the fast lane straight to `main`.
+urgent production fix takes the fast lane straight to `main`. The branch prefix
+decides the target; the canonical prefix → target table lives in
+[`aidd_docs/memory/vcs.md`](aidd_docs/memory/vcs.md#types).
 
 ```mermaid
 flowchart LR

aidd_docs/memory/vcs.md

@@ -16,15 +16,33 @@ type/ticket-short-description
 
 ### Types
 
-| Prefix | Usage | Branch from | PR target |
-| --- | --- | --- | --- |
-| `feat/` | New feature | `next` | `next` |
-| `fix/` | Bug fix | `next` | `next` |
-| `docs/` | Documentation only | `next` | `next` |
-| `refactor/` | Code change (no feat/fix) | `next` | `next` |
-| `chore/` | Build, config, deps | `next` | `next` |
-| `test/` | Add/update tests | `next` | `next` |
-| `hotfix/` | Urgent production fix | `main` | `main` |
+The single source of truth: find your row, read left to right — it tells you the
+branch to create, the label that applies, and where the PR goes. The branch
+**prefix** alone decides the target (not a label, not a board field); the
+`aidd-vcs:02-pull-request` skill reads this table to set the base automatically.
+
+| I want to… | Issue template | Branch | Commit | Label (auto) | PR targets |
+| ---------- | -------------- | ------ | ------ | ------------ | ---------- |
+| ship a feature | ✨ Feature | `feat/…` | `feat:` | `enhancement` | `next` |
+| fix a bug | 🐛 Bug | `fix/…` | `fix:` | `bug` | `next` |
+| change docs only | ✨ Feature | `docs/…` | `docs:` | `documentation` | `next` |
+| refactor (no behaviour change) | — | `refactor/…` | `refactor:` | — | `next` |
+| build / config / deps | — | `chore/…` | `chore:` | `dependencies` | `next` |
+| add or update tests | — | `test/…` | `test:` | — | `next` |
+| 🚨 urgent production fix | 🐛 Bug | `hotfix/…` | `fix:` | `bug` | **`main`** |
+
+#### Routing rule (strict)
+
+- Everything batches on `next` and ships in the weekly release.
+- **Only `hotfix/*` targets `main`** — an urgent production fix, out of cycle.
+
+Once the PR is open, the board advances on its own:
+`Todo → In review` (PR opened) `→ Ready` (review approved) `→ Done` (merged).
+
+Labels are **triage only**: they categorize, they never route. `security` is
+cross-cutting — add it to any kind when the change is security-sensitive. The
+"Commit" column shows the conventional type; the authoritative type list is the
+[Commit Convention](#commit-convention) below (mirrors `commitlint.config.cjs`).
 
 ### Examples
 

aidd_docs/plans/2026_06_23-unify-taxonomy/phase-1.md

@@ -0,0 +1,55 @@
+---
+status: done
+---
+
+# Instruction: Canonical routing table
+
+Part of [`plan.md`](./plan.md). Dependency root — author before all other phases.
+
+## Architecture projection
+
+```txt
+aidd_docs/memory/
+└── vcs.md   🔁  Branch-Naming "Types" table gains 2 columns (triage label,
+                 routing ✓/-) + a strict routing callout + a triage-only note.
+```
+
+## Tasks to do
+
+### `1)` Replace the branch "Types" table with the dense canonical table
+
+> One grid that maps kind → prefix → commit type → triage label → destination.
+
+1. Under `## Branch Naming Convention` → `### Types`, replace the current 4-column table with:
+
+   | Kind | Branch prefix | Commit type | Triage label | `next` | `main` |
+   | ---- | ------------- | ----------- | ------------ | :----: | :----: |
+   | Feature | `feat/` | `feat` | `enhancement` | ✓ | – |
+   | Fix | `fix/` | `fix` | `bug` | ✓ | – |
+   | Docs | `docs/` | `docs` | `documentation` | ✓ | – |
+   | Refactor | `refactor/` | `refactor` | – | ✓ | – |
+   | Chore | `chore/` | `chore` | `dependencies` | ✓ | – |
+   | Test | `test/` | `test` | – | ✓ | – |
+   | Hotfix | `hotfix/` | `fix` | `bug` | – | ✓ |
+
+2. Keep the existing `### Format` and `### Examples` blocks unchanged.
+
+### `2)` Add the strict routing callout + triage-only note
+
+> Make the rule unmissable and kill the label/route confusion.
+
+1. Immediately under the table, add a short callout, in substance:
+   - The branch **prefix alone** decides the PR target — not a label, not a board field.
+   - Everything batches on `next`; **only `hotfix/*` targets `main`** (urgent production fix, out of cycle).
+   - The `aidd-vcs:02-pull-request` skill reads this table to set the base branch automatically.
+2. Add the triage-only note: labels categorize, they never route; `security` is cross-cutting — add it to any kind when the change is security-sensitive.
+3. Confirm the commit-type and changelog definitions are untouched (the `## Commit Convention` section stays as-is; the table's "commit type" column is illustrative, not a redefinition).
+
+## Test acceptance criteria
+
+| Task | Acceptance criteria |
+| ---- | ------------------- |
+| 1 | The dense 6-column table renders in `vcs.md`; exactly one row routes to `main` (`hotfix`); all others to `next`. |
+| 1 | The table is the only place in the repo with the kind·prefix·label·✓/- grid (`grep -rl` for a unique cell string returns only `vcs.md`). |
+| 2 | A "routing rule (strict)" callout states prefix-decides-target and the single `hotfix→main` exception; a triage-only note is present. |
+| 2 | `## Commit Convention` section is byte-identical to before (no commit-type or scope changes). |

aidd_docs/plans/2026_06_23-unify-taxonomy/phase-2.md

@@ -0,0 +1,43 @@
+---
+status: done
+---
+
+# Instruction: Label set + dependabot (atomic)
+
+Part of [`plan.md`](./plan.md). **Atomic unit** — both files change together; never drop a label from one without the other (else dependabot recreates it ungoverned).
+
+## Architecture projection
+
+```txt
+.github/
+├── labels.yml       🔁  11 → 8 labels + triage-only header note.
+└── dependabot.yml   🔁  `labels:` keys lose `npm` and `github-actions`.
+```
+
+## Tasks to do
+
+### `1)` Trim `labels.yml` to 8 + header note
+
+> Keep triage types + required automation labels; cut the noise.
+
+1. Keep: `bug`, `enhancement`, `documentation`, `security`, `good first issue`, `dependencies`, `autorelease: pending`, `autorelease: tagged`.
+2. Remove: `help wanted`, `npm`, `github-actions`.
+3. Add a header comment: labels are **triage only**; routing is by branch prefix (see `aidd_docs/memory/vcs.md`); keep one triage label per change.
+4. Leave colors/descriptions of kept labels intact (refine `security` description to note it is cross-cutting).
+
+### `2)` Drop ecosystem labels from `dependabot.yml`
+
+> The `dependencies` umbrella is enough at this scale.
+
+1. In the `github-actions` ecosystem block, set `labels: ["dependencies"]` (remove `github-actions`).
+2. In the `npm` ecosystem block, set `labels: ["dependencies"]` (remove `npm`).
+3. Touch nothing else (schedule, prefixes, limits stay).
+
+## Test acceptance criteria
+
+| Task | Acceptance criteria |
+| ---- | ------------------- |
+| 1 | `grep '^- name:' .github/labels.yml` lists exactly the 8 kept labels; `help wanted`, `npm`, `github-actions` absent. |
+| 1 | Header comment states triage-only + routing-by-prefix + link to vcs.md. |
+| 2 | Both ecosystem blocks in `dependabot.yml` have `labels: ["dependencies"]` only. |
+| 1+2 | `grep -rn -e 'help wanted' -e '"npm"' -e 'github-actions' .github/labels.yml .github/dependabot.yml` returns no orphan reference to a dropped label. |

aidd_docs/plans/2026_06_23-unify-taxonomy/phase-3.md

@@ -0,0 +1,56 @@
+---
+status: done
+---
+
+# Instruction: Docs point to canonical (no duplication)
+
+Part of [`plan.md`](./plan.md). Depends on phase 1 (the anchor target must exist).
+
+## Architecture projection
+
+```txt
+.
+├── CONTRIBUTING.md   🔁  Inline label table (L75-80) → link to vcs.md table;
+│                         routing prose (L71) → short pointer + link.
+└── RELEASE.md        🔁  "Where your change goes" links the vcs.md table;
+                          flow mermaid kept; any restated routing prose trimmed.
+```
+
+## User Journey
+
+```mermaid
+flowchart TD
+  A[Contributor lost] --> B[CONTRIBUTING hub]
+  B -->|naming + routing| C[vcs.md table]
+  B -->|release flow| D[RELEASE.md]
+  B -->|who merges| E[GOVERNANCE.md]
+```
+
+## Tasks to do
+
+### `1)` De-duplicate `CONTRIBUTING.md`
+
+> It is already a hub; remove the one restated taxonomy.
+
+1. Replace the inline label table (the `| Label | When to use |` block) with a one-line pointer to the canonical table: triage labels + routing live in `aidd_docs/memory/vcs.md` (link to the `#types` anchor). Keep the PR-labelling instruction itself.
+2. Trim the routing prose ("Branch off `next`… `hotfix/*` off `main`…") to a short gist + link to the vcs.md table; do not restate the full table.
+3. Verify the three hub links resolve and are one hop each: naming/routing → vcs.md, release → RELEASE.md, merge → GOVERNANCE.md.
+4. Confirm the issue-template path still holds: opening a 🐛 / ✨ issue applies `bug` / `enhancement` automatically (no edit — verification only).
+
+### `2)` Point `RELEASE.md` at the canonical table
+
+> Anyone landing here finds the table by link, not a copy.
+
+1. In `## Where your change goes`, add a sentence linking the canonical prefix→target table at `aidd_docs/memory/vcs.md#types`.
+2. Keep the existing flow mermaid and the commit-type→changelog table (release domain, matches release-please-config — leave as-is).
+3. Ensure no prefix→target *table* is restated here (the mermaid is a flow diagram, allowed).
+
+## Test acceptance criteria
+
+| Task | Acceptance criteria |
+| ---- | ------------------- |
+| 1 | `CONTRIBUTING.md` no longer contains the `| Label | When to use |` table; a link to `vcs.md` triage/routing replaces it. |
+| 1 | CONTRIBUTING contains exactly one link each to vcs.md, RELEASE.md, GOVERNANCE.md reachable in one hop. |
+| 1 | Creating an issue via each template yields it pre-labelled (`labels:` keys confirmed present in both templates). |
+| 2 | `RELEASE.md` "Where your change goes" links `vcs.md#types`; no prefix→target table restated. |
+| 1+2 | A text search for a unique cell of the canonical grid returns hits only in `vcs.md`, not in CONTRIBUTING/RELEASE/GOVERNANCE. |