chore: promote next to main

.claude/hooks/worktree-create.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+// WorktreeCreate hook — base every new worktree on `next`, falling back to
+// `main` when the `next` branch does not exist.
+//
+// Docs: https://code.claude.com/docs/en/hooks#worktreecreate
+//   stdin : JSON { name } — the worktree name
+//   stdout: the created worktree path, and nothing else
+// This replaces Claude's default `git worktree add`.
+
+const { execFileSync } = require("node:child_process");
+const { readFileSync } = require("node:fs");
+const { join } = require("node:path");
+
+// Run a git command and return its trimmed stdout. git's own progress text is
+// forwarded to our stderr so this process's stdout stays reserved for the path.
+function git(...args) {
+  return execFileSync("git", args, {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "inherit"],
+  }).trim();
+}
+
+function branchExists(branch) {
+  try {
+    git("rev-parse", "--verify", "--quiet", `refs/heads/${branch}`);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function readWorktreeName() {
+  const payload = JSON.parse(readFileSync(0, "utf8"));
+  return payload.name;
+}
+
+function createWorktree() {
+  const worktreeName = readWorktreeName();
+  const baseBranch = branchExists("next") ? "next" : "main";
+
+  const repoRoot = git("rev-parse", "--show-toplevel");
+  const worktreePath = join(repoRoot, ".claude", "worktrees", worktreeName);
+  const newBranch = `worktree-${worktreeName}`;
+
+  git("worktree", "add", worktreePath, "-b", newBranch, baseBranch);
+
+  process.stdout.write(worktreePath + "\n");
+}
+
+createWorktree();

.claude/settings.json

@@ -12,5 +12,17 @@
     "aidd-pm@aidd-framework": true,
     "aidd-orchestrator@aidd-framework": true,
     "aidd-refine@aidd-framework": true
+  },
+  "hooks": {
+    "WorktreeCreate": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/worktree-create.js\""
+          }
+        ]
+      }
+    ]
   }
 }

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,7 +1,7 @@
 name: 🐛 Bug Report
 description: Report a bug or unexpected behaviour in the framework
-title: "fix: "
-labels: ["bug"]
+title: "fix(<scope>): "
+type: Bug
 body:
   - type: markdown
     attributes:

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,7 +1,7 @@
 name: ✨ Feature Request
 description: Propose new content or an improvement to the framework
-title: "feat: "
-labels: ["enhancement"]
+title: "feat(<scope>): "
+type: Feature
 body:
   - type: markdown
     attributes:

.github/ISSUE_TEMPLATE/roadmap.yml

@@ -0,0 +1,47 @@
+name: 🗺️ Roadmap item
+description: "Maintainer-authored work: a skill, a refactor, a rule to enforce"
+title: "<type>(<scope>): "
+type: Task
+body:
+  - type: markdown
+    attributes:
+      value: |
+        For maintainers planning framework work. Reporting a bug or asking for a feature as a user?
+        Use the **Bug Report** or **Feature Request** form instead.
+
+        The title carries its own scope, matching `commitlint.config.cjs`: `feat(aidd-pm):`, `fix(framework):`, `refactor(aidd-context):`.
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What is wrong or missing today. State the current behaviour, not the fix.
+      placeholder: The router of `10-learn` is 40 lines of its 153, denser than the four actions it routes to.
+    validations:
+      required: true
+  - type: textarea
+    id: scope
+    attributes:
+      label: Scope
+      description: What this change does. One bullet per deliverable.
+    validations:
+      required: true
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+      description: Checkboxes a reviewer can verify without asking the author. Each one observable.
+      value: |
+        - [ ]
+        - [ ]
+    validations:
+      required: true
+  - type: textarea
+    id: prior-art
+    attributes:
+      label: Prior art in this repo
+      description: What already exists that this builds on or duplicates. Cite the file and line. Leave empty if you checked and found none.
+  - type: textarea
+    id: out-of-scope
+    attributes:
+      label: Out of scope
+      description: What a reader would expect here and will not find, with where it lives instead.

.github/labels.yml

@@ -1,8 +1,12 @@
 # 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.
+# Labels do NOT categorize an issue. Issue types (Bug, Feature, Task) and the
+# org issue fields (Priority, Effort) do that, and the issue forms set the type.
+# A label here exists only when a bot or a human reads it, and nothing else can
+# carry the signal.
+#
+# Labels never decide where a PR targets — routing is by branch prefix
+# (see aidd_docs/memory/vcs.md).
 #
 # This file is the source of truth. When the GitHub label set drifts from
 # this file, sync manually with:
@@ -13,35 +17,19 @@
 # job). Plugins may create their own labels on install; those are documented in
 # the plugin, not here.
 
-# --- Triage --------------------------------------------------------------
-
-- name: bug
-  description: Something isn't working
-  color: d73a4a
-
-- name: enhancement
-  description: New feature or request
-  color: a2eeef
-
-- name: documentation
-  description: Improvements or additions to documentation
-  color: 0075ca
-
-- name: security
-  description: Security-sensitive issue or fix (cross-cutting, add to any kind)
-  color: B60205
+# --- Read by a human -----------------------------------------------------
 
 - name: good first issue
   description: Good for newcomers
   color: 7057ff
 
-# --- Dependencies --------------------------------------------------------
+# --- Applied by dependabot (.github/dependabot.yml) ----------------------
 
 - name: dependencies
   description: Dependency update (dependabot)
   color: 0366d6
 
-# --- Release tooling -----------------------------------------------------
+# --- Applied by release-please -------------------------------------------
 
 - name: "autorelease: pending"
   description: Release Please release PR awaiting merge

.github/workflows/back-merge.yml

@@ -74,6 +74,5 @@ jobs:
           gh issue create \
             --repo "${{ github.repository }}" \
             --title "Back-merge main into next failed (run ${{ github.run_id }})" \
-            --label "back-merge-failed" \
             --body "The automated back-merge of \`main\` into \`next\` failed, so \`next\` is drifting from the latest release. Resync manually by opening a PR from \`main\` into \`next\`. Run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}" \
           || echo "issue creation failed; check the run logs"

.github/workflows/ci.yml

@@ -88,6 +88,22 @@ jobs:
           GH_TOKEN: ${{ steps.app-token.outputs.token }}
         run: gh pr merge "${{ fromJSON(steps.release.outputs.pr).number }}" --squash --admin --repo "${{ github.repository }}"
 
+      # Pin GitHub's "Latest" badge to the umbrella marketplace release.
+      # release-please creates the umbrella + every plugin release in one run
+      # with no ordering guarantee, and GitHub marks whichever release is created
+      # last as "Latest" (the create API defaults make_latest to true). That
+      # lets a plugin release (e.g. aidd-dev-v2.3.0) outrank the marketplace
+      # version whenever a cycle ships plugins alongside the umbrella. Bare
+      # `tag_name` is the root "." package tag (the umbrella `v*`, the tag that
+      # carries the marketplace bundle); forcing it latest auto-unsets the plugin
+      # release that held the badge. The umbrella bumps every cycle, so a
+      # release run always has a root tag to pin.
+      - name: Pin umbrella release as latest
+        if: ${{ steps.release.outputs.release_created == 'true' }}
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: gh release edit "${{ steps.release.outputs.tag_name }}" --latest --repo "${{ github.repository }}"
+
   build-and-attach:
     name: Build and attach marketplace
     needs: [release-please]

.github/workflows/codeql.yml

@@ -31,15 +31,15 @@ jobs:
         uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
+        uses: github/codeql-action/init@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3
         with:
           languages: ${{ matrix.language }}
           queries: security-and-quality
 
       - name: Autobuild
-        uses: github/codeql-action/autobuild@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
+        uses: github/codeql-action/autobuild@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@8aad20d150bbac5944a9f9d289da16a4b0d87c1e # v4.36.2
+        uses: github/codeql-action/analyze@54f647b7e1bb85c95cddabcd46b0c578ec92bc1a # v4.36.3
         with:
           category: "/language:${{ matrix.language }}"

.github/workflows/dependabot-auto-merge.yml

@@ -25,6 +25,15 @@ jobs:
         id: meta
         uses: dependabot/fetch-metadata@25dd0e34f4fe68f24cc83900b1fe3fe149efef98 # v3.1.0
 
+      - name: Approve non-major updates
+        # Required-review rulesets (e.g. on `next`) block auto-merge until a
+        # review approves. Dependabot never gets one, so the app approves here.
+        # The app identity differs from the PR author, so the approval counts.
+        if: steps.meta.outputs.update-type != 'version-update:semver-major'
+        run: gh pr review --approve "${{ github.event.pull_request.html_url }}"
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+
       - name: Enable auto-merge for non-major updates
         if: steps.meta.outputs.update-type != 'version-update:semver-major'
         run: gh pr merge --auto --squash "${{ github.event.pull_request.html_url }}"

AGENTS.md

@@ -0,0 +1,54 @@
+# AGENTS.md
+
+> On the first message of a conversation, tell the user: "AI-Driven Development ON - Date: {current_date}, TZ: {current_timezone}."
+
+## Behavior
+
+- **Stay critical.** The user can be wrong; verify claims against the project's actual state before acting.
+- **Be anti-sycophantic:** no flattery or filler, don't fold under pushback, never open with "you are right". Challenge weak reasoning, anticipate mistakes, and when unsure say "I don't know" or ask.
+- **Surface tradeoffs and evaluate their impact** instead of hiding them.
+
+## Communication
+
+- **Answer first:** result before reason. Drop pleasantries (sure, of course, happy to) and hedging.
+- **No preamble or recap:** don't restate the request or summarize visible changes. Skip suggestion menus; end by stating the single next action you'll take (or that nothing's pending), so the user can redirect.
+- **Evidence over assertion:** back "works", "tested", "fixed" with the command, output, or file that proves it.
+- **Quote the shortest decisive line** of an error or log, not the whole dump.
+- **No tool-call narration.** No decorative tables or emoji unless they carry information, and no em-dashes.
+- **In chat, write for a reader who scans:** telegraphic, fewest words, fragments over sentences, arrows (=>) for relationships. Cut any word that doesn't change meaning. Normal prose in authored docs and code. Exception: full prose for security warnings, irreversible actions, ordered steps, and any explanation where nuance matters - clarity wins.
+
+## Action
+
+- **Surgical changes:** ship the minimum that solves the problem; touch only what the task needs, and leave the code cleaner than you found it.
+- **Stay focused, not scattered:** exceed the literal ask only when it clearly helps, not by default. When you spot an unrelated issue, note it in one line and keep going; detour only if it blocks the task.
+- **Solve your own issues first:** genuinely try to resolve it yourself before escalating to the human.
+- **Do not commit or push** unless the user asks.
+- **Don't assume your knowledge is current.**
+- **Placement discipline:** for every plugin change, think hard about where responsibility belongs; follow `docs/ARCHITECTURE.md`.
+- **Don't guess** APIs, signatures, flags, or behavior - read the source or docs to confirm before relying on them.
+- **Ambiguous or expensive task:** ask one sharp question to pin down scope before building, rather than guess.
+- **Batch independent operations** in one pass, not one at a time.
+- **Fan out** independent subtasks to parallel subagents when you own the overall flow and the work is genuinely parallel.
+- **Before adding any instruction, finding, or rule, check whether an existing one already covers or contradicts it.** If so, don't add a parallel: delete it, merge it into the stronger one, or rewrite with explicit scope and priority.
+- **Name by intention, not mechanism:** describe the goal or responsibility, not the tool or file format.
+
+## Memory Management
+
+Project docs, memory, specs, and plans live in `aidd_docs/`.
+
+### Project memory
+
+<aidd_project_memory>
+@aidd_docs/memory/architecture.md
+@aidd_docs/memory/browsing.md
+@aidd_docs/memory/codebase-map.md
+@aidd_docs/memory/coding-assertions.md
+@aidd_docs/memory/deployment.md
+@aidd_docs/memory/project-brief.md
+@aidd_docs/memory/testing.md
+@aidd_docs/memory/vcs.md
+</aidd_project_memory>
+
+- If the block above is empty, run `ls -1tr aidd_docs/memory/` and read each file.
+- Load `aidd_docs/memory/external/*` when the user asks.
+- Load `aidd_docs/memory/internal/*` when the task needs it.