diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 60d26dec..c7c6ecca 100644 --- a/.github/dependabot.yml +++ b/.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" diff --git a/.github/labels.yml b/.github/labels.yml index 48bc27cd..25ecc914 100644 --- a/.github/labels.yml +++ b/.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" diff --git a/.github/workflows/back-merge.yml b/.github/workflows/back-merge.yml index 2a234956..9bdf4af0 100644 --- a/.github/workflows/back-merge.yml +++ b/.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 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 3334d65f..356729c1 100644 --- a/.github/workflows/ci.yml +++ b/.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 diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml index b2bd1ab6..68b81d32 100644 --- a/.github/workflows/codeql.yml +++ b/.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 diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml index b3ae480a..a719188e 100644 --- a/.github/workflows/validate.yml +++ b/.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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1fb74f33..ff1f68f2 100644 --- a/CONTRIBUTING.md +++ b/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). diff --git a/RELEASE.md b/RELEASE.md index 6b56092c..8eb93edc 100644 --- a/RELEASE.md +++ b/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 diff --git a/aidd_docs/memory/vcs.md b/aidd_docs/memory/vcs.md index 4fc34de5..2f3c7e46 100644 --- a/aidd_docs/memory/vcs.md +++ b/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 diff --git a/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-1.md b/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-1.md new file mode 100644 index 00000000..5ef7e5b2 --- /dev/null +++ b/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). | diff --git a/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-2.md b/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-2.md new file mode 100644 index 00000000..3a4b9359 --- /dev/null +++ b/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. | diff --git a/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-3.md b/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-3.md new file mode 100644 index 00000000..6e16a94d --- /dev/null +++ b/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. | diff --git a/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-4.md b/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-4.md new file mode 100644 index 00000000..c1fa8f54 --- /dev/null +++ b/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-4.md @@ -0,0 +1,64 @@ +--- +status: done +--- + +# Instruction: PR automation routes by prefix + +Part of [`plan.md`](./plan.md). Depends on phase 1 (the skill reads the canonical table from memory). Keep the plugin **generic** — it reads project memory, never hardcodes `next`. + +## Architecture projection + +```txt +plugins/aidd-vcs/skills/02-pull-request/ +├── actions/01-pull-request.md 🔁 Base resolution derives target from branch +│ prefix via project memory; +auto-label step. +└── assets/branch.md 🔁 Stale `aidd_docs/` → `docs/` prefix. +``` + +## User Journey + +```mermaid +flowchart TD + A[Head branch e.g. feat/x] --> B{prefix in project-memory table?} + B -->|yes| C[base = that row's PR target] + B -->|no| D[fallback: origin/HEAD, then main/master/develop/staging] + C --> E[open draft PR] + D --> E + E --> F[apply matching triage label if defined + exists] +``` + +## Tasks to do + +### `1)` Base resolution by branch prefix + +> Fixes feat/→main: `next` was absent from the candidate list. + +1. In `## Process` step 3 (Base resolution), insert a match BEFORE the `origin/HEAD` fallback: if the project's branch-naming convention (project memory) maps the head branch's prefix to a PR target, use that target. +2. Keep the existing `origin/HEAD` → `main/master/develop/staging` as the fallback when no prefix mapping exists. +3. Keep it generic: phrase as "the branch-naming convention in project memory", never hardcode `next`. +4. Surface the chosen base and the reason ("prefix `feat/` → `next` per project convention") during the step-7 validation. + +### `2)` Auto-apply the triage label + +> A PR is born typed, matching the issue model. + +1. Add a numbered step after "Open draft": when the convention maps the head prefix to a triage label and that label exists in the repo, apply it; skip silently otherwise. +2. State explicitly: labels triage only; this step never changes the base resolved earlier. +3. Update the `## Test` checklist to cover prefix-derived base + label application; extend Outputs if a label field is warranted. + +### `3)` Fix the stale generic template + +> `branch.md` is a generic distributable template; correct the bug only. + +1. In `assets/branch.md` Types table, change the `aidd_docs/` prefix row to `docs/`. +2. No other change — it stays a generic naming template (no `next`/`main`, no repo-specific routing). + +## Test acceptance criteria + +| Task | Acceptance criteria | +| ---- | ------------------- | +| 1 | Step 3 lists a prefix→target derivation via project memory BEFORE the origin/HEAD fallback; no literal `next` hardcoded. | +| 1 | Tracing the doc logic: a `feat/*` head resolves base `next`; `hotfix/*` resolves `main` (per the vcs.md table). | +| 2 | A numbered step applies the prefix-mapped triage label post-open, gated on label existence, marked triage-only. | +| 2 | `## Test` checklist asserts the prefix-derived base and the applied label. | +| 3 | `assets/branch.md` shows `docs/`; no `aidd_docs/` remains; no `next`/`main` added. | diff --git a/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-5.md b/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-5.md new file mode 100644 index 00000000..2ffa2ac9 --- /dev/null +++ b/aidd_docs/plans/2026_06_23-unify-taxonomy/phase-5.md @@ -0,0 +1,67 @@ +--- +status: done +--- + +# Instruction: Board playbook (Project 8) + +Part of [`plan.md`](./plan.md). The board is GitHub Project config, not repo files — deliver a **playbook** the maintainer applies. Independent of phases 1-4 (can run in parallel). + +## Architecture projection + +```txt +docs/ +└── MAINTAINERS.md 🔁 New "## Project board (Project 8)" section: the + field/status/view playbook (gh commands + UI steps). +``` + +> Confirm `MAINTAINERS.md` is the right host at implement; if it does not fit, create `docs/BOARD.md` and link it from MAINTAINERS + CONTRIBUTING. + +## User Journey + +```mermaid +flowchart TD + A[Maintainer opens playbook] --> B[Drop Work type + Phases] + B --> C[Keep Priority] + C --> D[Set Status options] + D --> E[Wire built-in workflows] + E --> F[Add Timeline view] +``` + +## Tasks to do + +### `1)` Write the field-cleanup steps + +> Each board property answers one question; kill the duplicates. + +1. **Drop "Work type"** (duplicates the Type label) and **"Phases"** (duplicates Status/Milestone). Provide the `gh` inspection + deletion commands, e.g.: + - `gh project field-list 8 --owner ai-driven-dev` to read field IDs. + - `gh project field-delete ` for each dropped field. +2. **Keep Priority** — state explicitly it stays (P0·P1·P2), no action. + +### `2)` Status options + automation + +> Status carries the flow and advances itself. + +1. Set Status single-select options: `Todo · In progress · In review · Ready · Done`. Note this is a single-select field edit (UI; `gh project field-create` only creates new fields — document the UI path to edit the existing Status options, with the `gh` create path as the from-scratch alternative). +2. Document the built-in workflow wiring (Project → Workflows, UI): + - item added → **Todo** + - PR linked / ready for review → **In review** + - code review approved → **Ready** + - PR merged / issue closed → **Done** +3. Flag which transitions are GitHub built-ins vs. manual moves (In progress is typically manual). + +### `3)` Timeline view + verification checklist + +> The "phases" replacement Alex asked for. + +1. Add a **Timeline** view (UI: New view → Timeline; date field = target/milestone). Document the steps. +2. End the section with a tick-box checklist mirroring the spec board done-when: Work type removed · Phases removed · Priority kept · Status options set · automation enabled · Timeline view present. + +## Test acceptance criteria + +| Task | Acceptance criteria | +| ---- | ------------------- | +| 1 | Playbook gives concrete `gh project field-list`/`field-delete` commands for Work type + Phases, and states Priority is kept. | +| 2 | Playbook lists the 5 Status options and the 4 built-in transitions, marking built-in vs manual. | +| 3 | Playbook documents adding a Timeline view and ends with a board-done-when checklist. | +| all | Section is self-contained: a maintainer can apply it end-to-end without re-deriving anything from the Loom. | diff --git a/aidd_docs/plans/2026_06_23-unify-taxonomy/plan.md b/aidd_docs/plans/2026_06_23-unify-taxonomy/plan.md new file mode 100644 index 00000000..2e8f91ca --- /dev/null +++ b/aidd_docs/plans/2026_06_23-unify-taxonomy/plan.md @@ -0,0 +1,60 @@ +--- +objective: "The change taxonomy + routing rule live in one canonical table (vcs.md); every other surface links to it or derives from it; the board playbook is delivered." +status: implemented +--- + +# Plan: Unify the change taxonomy into one source of truth + a projected board + +## Overview + +| Field | Value | +| ---------- | --------------------------------------------------------------------- | +| **Goal** | One canonical routing table; all surfaces link/derive; board playbook. | +| **Source** | [`2026_06_23-unify-taxonomy.md`](../../specs/2026_06/2026_06_23-unify-taxonomy.md) (spec, VALID 100/100) | + +## Phases + +| # | Phase | File | +| --- | ------------------------------ | ---------------------------- | +| 1 | Canonical routing table | [`phase-1.md`](./phase-1.md) | +| 2 | Label set + dependabot (atomic)| [`phase-2.md`](./phase-2.md) | +| 3 | Docs point to canonical | [`phase-3.md`](./phase-3.md) | +| 4 | PR automation routes by prefix | [`phase-4.md`](./phase-4.md) | +| 5 | Board playbook (Project 8) | [`phase-5.md`](./phase-5.md) | + +## Resources + +| Source | Verified | +| ------------- | --------------------------- | +| `aidd_docs/memory/vcs.md` | Holds branch table (prefix · from · target) — no label column, no ✓/-. Becomes the dense canonical. | +| `RELEASE.md` | "Where your change goes" has a flow mermaid + commit→changelog table (matches release-please-config). | +| `CONTRIBUTING.md` | Already a hub: links vcs.md (commits L67), RELEASE (routing L71), GOVERNANCE (merge). Inline label table L75-80 is the one duplication. | +| `.github/labels.yml` | 11 labels. | +| `.github/dependabot.yml` | Applies `dependencies`+`npm` and `dependencies`+`github-actions` — must drop in lockstep with labels.yml. | +| `.github/ISSUE_TEMPLATE/bug_report.yml` / `feature_request.yml` | Already carry `labels: ["bug"]` / `["enhancement"]` — done-when "issue born typed" PRE-SATISFIED; verify-only. | +| `plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md` | Base resolution candidate list `main/master/develop/staging` — `next` absent (the feat/→main bug). | +| `docs/MAINTAINERS.md` | Existing maintainer-ops home — proposed host for the board playbook section. | + +## Decisions + +| Decision | Why | +| ---------- | -------------- | +| Canonical table lives in `vcs.md` (AI-auto-loaded memory) | PR skill + AI both read memory; flipping to a human doc would couple automation to a non-loaded file. | +| RELEASE keeps its flow mermaid | A flow diagram ≠ the mapping table; the prefix→target *table* stays single-homed in vcs.md, RELEASE links it. | +| Board playbook appended to `docs/MAINTAINERS.md` | Maintainer-ops already lives there; avoids a new orphan doc (no-sprawl ethos). Confirm fit at implement. | +| Issue templates: no edit | They already apply the Type label; editing would be churn. | +| Plugin `branch.md` / PR action stay generic | Distributable layer (ARCHITECTURE.md); they read project memory, never hardcode `next`. | + +## Spec done-when → phase coverage + +| Spec done-when | Phase | +| -------------- | ----- | +| Mapping exists once; others link | 1 (author) + 3 (link) | +| Strict: single production-routed row | 1 | +| Front-door routes 3 destinations, one hop | 3 | +| Label set reduced, triage-only, no routing-by-label | 2 | +| Dropped labels not recreated by automation | 2 | +| Issue born typed | pre-satisfied (verify in 3) | +| PR base + label by prefix | 4 | +| Board fields orthogonal (Work type, Phases gone; Priority kept) | 5 | +| Status lifecycle + automation + Timeline view | 5 | diff --git a/aidd_docs/specs/2026_06/2026_06_23-unify-taxonomy.md b/aidd_docs/specs/2026_06/2026_06_23-unify-taxonomy.md new file mode 100644 index 00000000..d540653c --- /dev/null +++ b/aidd_docs/specs/2026_06/2026_06_23-unify-taxonomy.md @@ -0,0 +1,49 @@ +# Unify the change taxonomy into one source of truth + a projected board + +## Target + +Define the change-classification taxonomy and its routing rule **once**, in a single canonical place that every other contributor-facing surface and the project board links to or derives from — never restates. + +## Hard constraints + +- One canonical home for the taxonomy/routing definition; every other document links to it rather than restating it (repo rule: never duplicate across docs). +- Routing (which branch a change targets) is **derived from the branch prefix**, never stored as a label or a board field. +- The canonical definition must be consumable by both the AI tooling (the always-loaded project memory) and humans, without a second copy existing. +- The distributable plugin templates stay generic — they are products shipped to other projects, not mirrors of this repo's own instance. +- Commit-type and changelog-section definitions are left unchanged (already aligned to Conventional Commits and the release tool). +- Board changes are delivered as a maintainer playbook (the board is external config), not as repo file edits; repo deliverables must not assume the board can be edited as repo files. +- Each board field and each label answers a distinct question; no field may duplicate another field or a label. + +## Non-goals + +- Renaming the `enhancement` label to `feature` — `enhancement` stays; the spec only documents that it is the label form of a `feat`/feature change. +- Any label-sync workflow or board automation beyond GitHub's built-in project workflows. +- Changing the allowed commit types or the changelog sections. +- Restructuring the generic plugin pull-request / branch templates beyond correcting a stale, incorrect prefix value. +- Building the board for the maintainer — the spec supplies the playbook; applying it is the maintainer's act. + +## Done-when + +- The change-kind → routing (next vs main) mapping exists in exactly one document; searching the repo finds that mapping rendered once, and every other doc that needs it contains a link to that single home. *(verify: text search shows one occurrence of the mapping table; the release doc and the contributor doc each link to it.)* +- The routing rule is strict and unambiguous: exactly one branch prefix routes to the production branch (the urgent-fix prefix); all other prefixes route to the integration branch. *(verify: the canonical table shows a single production-routed row.)* +- A single contributor front-door document routes a reader to naming+routing, the release flow, and the merge/governance rules, each reachable in one hop. *(verify: the front-door doc contains a link to each of the three; and a text search for the canonical routing table/sentence returns hits only in its canonical home, not in the front-door, release, or governance docs.)* +- The issue/PR label set is reduced to triage-type labels plus the automation labels the tooling requires; no label encodes routing, and a header states labels are triage-only. *(verify: the label list equals the agreed reduced set; a search finds no label used to decide routing.)* +- Labels removed from the canonical list are not recreated by any automation. *(verify: the dependency-update config no longer references the removed labels.)* +- An issue opened from a project issue template is created already carrying its Type label, with no manual step. *(verify: creating an issue via each template yields an issue pre-labelled with its type.)* +- A pull request opened by the project's PR automation targets the branch determined solely by the head branch's prefix, and carries the matching Type label. *(verify: a feature-prefixed branch produces a PR targeting the integration branch; the urgent-fix prefix targets production; the type label is present.)* +- The board exposes only orthogonal fields — the field that duplicated the Type label is gone, and the redundant phase field is gone — while Priority remains. *(verify: board playbook checklist confirms both fields removed and Priority kept.)* +- The board Status field carries the agreed lifecycle states and advances through them via built-in automation, and a Timeline view exists. *(verify: board playbook checklist confirms the Status options, the enabled built-in transitions, and the Timeline view.)* + +## Stakeholders + +- Decider: Baptiste (resolves any taxonomy/placement tradeoff). +- Owner: Baptiste & Alex (maintainers, long-term owners of the convention and the board). +- Consumer: public contributors (read the docs/board, open issues/PRs) and the AI tooling (reads the canonical memory, opens PRs, applies labels). + +## Context + +- Source: Alex's Loom review — the same taxonomy is currently re-spelled across branch prefix, commit type, label, and the board "Work type" field, and the four drift; a maintainer got lost finding routing info. The ask: fewer, clearer, non-duplicated, strict rules. +- Guiding principle agreed in brainstorm: one taxonomy, defined once, projected everywhere (docs, label, board field, timeline), advanced by automation, never re-typed by a human. +- Orthogonal property model agreed: Type → label; Priority → board field; Status → board field (auto-advanced); When → milestone/timeline; Effort/onboarding → the good-first-issue label; Routing → derived from branch prefix. +- Existing anchors that constrain the canonical definition: the commit linter (Conventional Commits) and the release tool's changelog sections are already correct and authoritative for their domains; the taxonomy mirrors them, it does not redefine them. +- The board is GitHub Project 8 (public roadmap + maintainer triage), configured outside the repo. diff --git a/docs/MAINTAINERS.md b/docs/MAINTAINERS.md index 92d37f8a..06b0dc8a 100644 --- a/docs/MAINTAINERS.md +++ b/docs/MAINTAINERS.md @@ -15,10 +15,73 @@ How to operate this repository day to day. For **who** may do what and the decis ## Daily -- **Triage issues.** New issues auto-add to board #8. Set `Status` / `Area` / `Priority` / `Work Type`; link under an epic (native sub-issues) if relevant. +- **Triage issues.** New issues auto-add to board #8. Set `Status` / `Area` / `Priority`; link under an epic (native sub-issues) if relevant. **Type** is the issue/PR label, not a board field (see [Project board layout](#project-board-project-8)). - **Roadmap.** Priority is set by the community vote (mechanism in `GOVERNANCE.md`). Accepted items live on board #8 - keep `ROADMAP.md` as a pointer, do not maintain a second list. - **Review PRs.** Every PR needs a Habilité (CODEOWNERS) approval; checks `lefthook`, `Commitlint` must pass; squash-merge. +## Project board (Project 8) + +The board is a **view** of the same taxonomy the docs define — it never invents its own. Each property answers one question: **Type** = the label, **Priority** = how urgent, **Status** = where in the flow, **When** = the Timeline. Routing (`next` vs `main`) is *not* a board property — it derives from the branch prefix ([routing table](../aidd_docs/memory/vcs.md#types)). + +Apply this layout once (org-admin or board-write needed). Read field IDs first: + +```bash +gh project field-list 8 --owner ai-driven-dev # note the IDs you need below +``` + +### Fields + +- **Drop `Work type`** — duplicates the Type label. **Drop `Phases`** — duplicates Status/Milestone (and no milestone exists, so it is noise): + ```bash + gh project field-delete --id + gh project field-delete --id + ``` +- **Keep `Priority`** (P0 · P1 · P2) and `Area`. No action. +- **`Status`** — single-select options, in order: `Todo` · `In progress` · `In review` · `Ready` · `Done`. `Status` is a built-in field; edit its options in the UI (Board → `Status` field header → Edit values). The CLI only *creates* fields, so use it only if you are rebuilding from scratch: + ```bash + # from-scratch alternative only — NOT for editing the existing Status field + gh project field-create 8 --owner ai-driven-dev --name Status \ + --data-type SINGLE_SELECT \ + --single-select-options "Todo,In progress,In review,Ready,Done" + ``` + +### Status automation (UI: Project → ⋯ → Workflows) + +GitHub built-in workflows drive most transitions; `In progress` is the one manual move. + +| Trigger (built-in) | Set `Status` to | +| ------------------ | --------------- | +| Item added to project | `Todo` | +| Pull request linked / ready for review | `In review` | +| Code review approved | `Ready` | +| Pull request merged · item closed | `Done` | +| *(manual — picked up by a maintainer)* | `In progress` | + +### Timeline view + +Replaces the old "Phases". UI: **New view → Timeline**, date field = the Milestone / target date. Use it as the roadmap horizon (`this week` / `next` / `later`). + +### Apply checklist + +- [ ] `Work type` field deleted +- [ ] `Phases` field deleted +- [ ] `Priority` kept +- [ ] `Status` options = Todo · In progress · In review · Ready · Done +- [ ] Built-in Status workflows enabled (added→Todo, ready→In review, approved→Ready, merged/closed→Done) +- [ ] Timeline view present + +## Labels + +[`.github/labels.yml`](../.github/labels.yml) is the canonical set (triage only — routing is by branch prefix). The documented sync loop **creates/updates** from the file; it does **not** delete. So when you remove a label from the file, also delete it on GitHub: + +```bash +gh label delete "help wanted" --yes +gh label delete npm --yes +gh label delete "github-actions" --yes +``` + +Dependabot labels its PRs `dependencies` only (ecosystem sub-labels were dropped); confirm `.github/dependabot.yml` does not re-add a deleted label before deleting it. + ## Releases release-please opens/updates a `chore: release main` PR on each push to `main`. diff --git a/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md b/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md index 995eb329..cffa5b7c 100644 --- a/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md +++ b/plugins/aidd-vcs/skills/02-pull-request/actions/01-pull-request.md @@ -29,15 +29,20 @@ is_draft: true 2. **Branch identity**. Read current head via `git rev-parse --abbrev-ref HEAD`. 3. **Base resolution**. Pick first match: - `base_branch` provided -> use it - - default -> inspect `git symbolic-ref refs/remotes/origin/HEAD`, then candidate list `main`, `master`, `develop`, `staging`; surface the chosen value during validation + - the branch-naming convention in project memory maps the head branch's prefix to a PR target (e.g. `feat/` -> `next`, `hotfix/` -> `main`) -> use that target + - default -> inspect `git symbolic-ref refs/remotes/origin/HEAD`, then candidate list `main`, `master`, `develop`, `staging` + - surface the chosen value and the reason during validation 4. **Collect changes**. Run `git log ..HEAD --pretty=fuller` and `git diff ...HEAD --stat` to summarize commits and impacted files. 5. **Read template**. Load `assets/pull_request.md` and any contributing rules from `assets/CONTRIBUTING.md`. 6. **Fill template**. Generate a concise title and a body that follows the template structure, using the change summary from step 4. 7. **Validate with user**. Show title, body, and detected base branch. Apply `template_overrides` when provided. Wait for explicit user approval. 8. **Open draft**. Invoke the configured VCS tool to create the request as a draft, passing base, title, and body. Capture the returned URL and number. -9. **Return** the structured Outputs block. +9. **Set triage label**. When the branch-naming convention maps the head branch's prefix to a triage label (e.g. `feat/` -> `enhancement`, `fix/` -> `bug`) and that label exists in the repo, apply it. Skip silently when there is no mapping or no matching label. Labels triage only; they never change the base resolved in step 3. +10. **Return** the structured Outputs block. ## Test - **Tool view**: querying the configured VCS tool for the created request returns a record where `url` equals `pr_url`, `base` equals the resolved base branch, and the draft flag is true. +- **Prefix routing**: a head branch whose prefix is mapped in project memory resolves `base` to that prefix's target (e.g. `feat/*` -> `next`, `hotfix/*` -> `main`), not the `origin/HEAD` default. +- **Triage label**: when the head prefix maps to a triage label that exists in the repo, the created request carries that label. - **Reachable**: the created request is reachable at `pr_url` and lists the head branch as the current branch. diff --git a/plugins/aidd-vcs/skills/02-pull-request/assets/branch.md b/plugins/aidd-vcs/skills/02-pull-request/assets/branch.md index 2ef27410..70b0c16a 100644 --- a/plugins/aidd-vcs/skills/02-pull-request/assets/branch.md +++ b/plugins/aidd-vcs/skills/02-pull-request/assets/branch.md @@ -18,7 +18,7 @@ type/ticket-short-description | ------------ | ------------------------- | | `feat/` | New feature | | `fix/` | Bug fix | -| `aidd_docs/` | Documentation only | +| `docs/` | Documentation only | | `refactor/` | Code change (no feat/fix) | | `chore/` | Build, config, deps | | `test/` | Add/update tests |