ai-driven-dev · blafourcade · Jun 19, 2026 · Jun 19, 2026 · Jun 19, 2026
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -9,47 +9,41 @@
   "plugins": [
     {
       "name": "aidd-context",
-      "version": "1.0.0",
       "source": "./plugins/aidd-context",
       "description": "Knowledge production: project bootstrap, project init, generation of context artifacts (skills, agents, rules, commands, hooks), mermaid diagrams, learn, discovery",
       "strict": true,
       "recommended": true
     },
     {
       "name": "aidd-dev",
-      "version": "1.0.0",
       "source": "./plugins/aidd-dev",
       "description": "Code transformation: Dev SDLC orchestrator (code-shipping pipeline), plan, assert, audit, review, test, refactor, debug, for-sure. Hosts engineering agents.",
       "strict": true,
       "recommended": true
     },
     {
       "name": "aidd-vcs",
-      "version": "1.0.0",
       "source": "./plugins/aidd-vcs",
       "description": "External artifacts: commit, pull-request, release-tag, issue-create",
       "strict": true,
       "recommended": true
     },
     {
       "name": "aidd-pm",
-      "version": "1.0.0",
       "source": "./plugins/aidd-pm",
       "description": "Product management: ticket-info, user-stories-create, prd, spec",
       "strict": true,
       "recommended": true
     },
     {
       "name": "aidd-orchestrator",
-      "version": "1.0.0",
       "source": "./plugins/aidd-orchestrator",
       "description": "Async development orchestration: turn ready issues into pull requests, then iterate on review feedback until a human takes over.",
       "strict": true,
       "recommended": false
     },
     {
       "name": "aidd-refine",
-      "version": "1.0.0",
       "source": "./plugins/aidd-refine",
       "description": "Meta-cognition: refine input through brainstorming, refine output through challenge and condensed communication mode.",
       "strict": true,

diff --git a/.github/rulesets/next.json b/.github/rulesets/next.json
@@ -0,0 +1,39 @@
+{
+  "name": "next protection",
+  "target": "branch",
+  "enforcement": "active",
+  "bypass_actors": [
+    {"actor_id": 3959336, "actor_type": "Integration", "bypass_mode": "always"},
+    {"actor_id": 11783938, "actor_type": "Team", "bypass_mode": "pull_request"}
+  ],
+  "conditions": {
+    "ref_name": {
+      "include": ["refs/heads/next"],
+      "exclude": []
+    }
+  },
+  "rules": [
+    {
+      "type": "pull_request",
+      "parameters": {
+        "required_approving_review_count": 0,
+        "dismiss_stale_reviews_on_push": false,
+        "require_code_owner_review": false,
+        "require_last_push_approval": false,
+        "required_review_thread_resolution": false
+      }
+    },
+    {
+      "type": "required_status_checks",
+      "parameters": {
+        "strict_required_status_checks_policy": false,
+        "required_status_checks": [
+          {"context": "lefthook (framework-local checks)"},
+          {"context": "Commitlint"}
+        ]
+      }
+    },
+    {"type": "non_fast_forward"},
+    {"type": "deletion"}
+  ]
+}
diff --git a/.github/workflows/back-merge.yml b/.github/workflows/back-merge.yml
@@ -0,0 +1,52 @@
+name: Back-merge
+
+# After a release on main, sync main back into next so its changelog, manifest,
+# and version bumps do not drift. No conflict -> push next directly (the App is
+# an "always" bypass actor on next). Conflict -> open a PR for a human.
+
+on:
+  release:
+    types: [published]
+
+concurrency:
+  group: back-merge
+  cancel-in-progress: false
+
+permissions: {}
+
+jobs:
+  back-merge:
+    name: Back-merge main into next
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        id: app-token
+        with:
+          app-id: ${{ secrets.AIDD_BOT_APP_ID }}
+          private-key: ${{ secrets.AIDD_BOT_PRIVATE_KEY }}
+
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6.0.3
+        with:
+          ref: next
+          fetch-depth: 0
+          token: ${{ steps.app-token.outputs.token }}
+
+      - name: Merge main into next
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          git config user.name "aidd-bot[bot]"
+          git config user.email "aidd-bot[bot]@users.noreply.github.com"
+          git fetch origin main
+          if git merge --no-edit origin/main; then
+            git push origin next
+          else
+            git merge --abort
+            BRANCH="back-merge/main-to-next-${{ github.run_id }}"
+            git checkout -b "$BRANCH" origin/main
+            git push origin "$BRANCH"
+            gh pr create --base next --head "$BRANCH" \
+              --title "chore: back-merge main into next (conflicts)" \
+              --body "Automated back-merge hit conflicts (CHANGELOG / manifest / version files). Resolve manually, then merge into next." \
+              --repo "${{ github.repository }}"
+          fi
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -74,6 +74,20 @@ jobs:
           config-file: release-please-config.json
           manifest-file: .release-please-manifest.json
 
+      # Auto-merge the Release PR release-please just opened/updated, with the
+      # App token. `--admin` is required: a plain `gh pr merge` is refused by the
+      # branch policy ("base branch policy prohibits the merge") even for a
+      # bypass actor (verified in a sandbox). `--admin` performs the override
+      # merge that the ruleset's bypass_actors entry permits for this App.
+      # An App-token merge also re-fires the `push: main` and `release: published`
+      # workflows that a GITHUB_TOKEN merge would not.
+      # Guard on prs_created (PR opened), not releases_created (fires on merge).
+      - name: Auto-merge the Release PR
+        if: ${{ steps.release.outputs.prs_created == 'true' }}
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: gh pr merge "${{ fromJSON(steps.release.outputs.pr).number }}" --squash --admin --repo "${{ github.repository }}"
+
   build-and-attach:
     name: Build and attach marketplace
     needs: [release-please]

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -64,24 +64,11 @@ Format: `<type>(<scope>): description`.
 git commit -m "feat(aidd-dev): add for-sure skill"
 ```
 
-**Scope** - one per commit (split cross-plugin changes):
-
-| Scope | Path |
-| ----- | ---- |
-| `aidd-context` / `aidd-dev` / `aidd-vcs` / `aidd-pm` / `aidd-orchestrator` / `aidd-refine` | the matching `plugins/<name>/` |
-| `marketplace` | `.claude-plugin/marketplace.json` |
-| `framework` | root: scripts, CI, configs, docs, `aidd_docs/` |
-
-**Type** - drives the release:
-
-- `feat` → minor · `fix` / `perf` → patch · `!` or `BREAKING CHANGE:` → major
-- `docs` / `refactor` / `style` / `test` / `build` / `ci` / `chore` → no release
-
-Versioning and the release bundles are automated - see [Releases](#releases).
+One scope per commit (split cross-plugin changes). The types, the scopes, and the rules live in [`aidd_docs/memory/vcs.md`](aidd_docs/memory/vcs.md#commit-convention) - it mirrors `commitlint.config.cjs`, the source of truth. **Type** drives the release; see [`RELEASE.md`](./RELEASE.md) for what each type produces.
 
 ## 3. Open a pull request
 
-- Work on a branch, not `main`.
+- Branch off `next` and target `next` (the integration branch); `hotfix/*` branches off `main` for urgent production fixes. See [`RELEASE.md`](./RELEASE.md).
 - **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:
 
@@ -97,16 +84,14 @@ Versioning and the release bundles are automated - see [Releases](#releases).
 
 ## Releases
 
-Automated by [release-please](https://github.com/googleapis/release-please) in manifest mode. The repo ships **7 independently-versioned packages** (root `aidd-framework` + the 6 plugins); each bumps from the conventional commits touching its path.
+How releases flow (the `main`/`next` model, weekly cadence, hotfix, auto-merge) is in [`RELEASE.md`](./RELEASE.md); the release tooling is in [`aidd_docs/memory/vcs.md`](aidd_docs/memory/vcs.md). What a release produces, for contributors:
 
-- Every push to `main` opens / updates a `chore: release main` PR (changelog + version bumps).
-- Merging it tags each bumped package and creates the GitHub Releases; CI then attaches the bundles:
+- **7 independently-versioned packages** (root `aidd-framework` + the 6 plugins).
+- On release, CI attaches the bundles:
   - `aidd-framework-marketplace-X.Y.Z.zip` - the Claude Code marketplace (`.claude-plugin/` + `plugins/`); kept as the legacy Claude alias of `aidd-framework-claude-marketplace-X.Y.Z.zip`.
   - `<plugin>-vX.Y.Z.zip` - per released plugin.
   - `aidd-framework-<tool>-<mode>-X.Y.Z.zip` - **per-tool distributions** built by `aidd-cli` (`framework build`) on the root release: 4 marketplace (claude/cursor/copilot/codex) + 5 flat (+opencode, flat-only) = 9 archives. Produced by the `build-per-tool` matrix job in `.github/workflows/ci.yml`, pinned to a specific `@ai-driven-dev/cli` version.
 
-Config: `release-please-config.json` + `.release-please-manifest.json` (pre-releases, forced versions, and recovery are driven through those files).
-
 ## Reporting issues
 
 [Open an issue](https://github.com/ai-driven-dev/framework/issues/new/choose) (🐛 Bug or ✨ Feature). New issues are auto-added to the [AIDD Roadmap board](https://github.com/orgs/ai-driven-dev/projects/8). For **usage questions**, use [Discussions](https://github.com/ai-driven-dev/framework/discussions), not issues (see [`SUPPORT.md`](./.github/SUPPORT.md)).

diff --git a/GOVERNANCE.md b/GOVERNANCE.md
@@ -76,13 +76,19 @@ none object.
 - **Conflict of interest**: a Habilité with a stake in a PR discloses it and is
   not the sole approver (a second Habilité approval becomes mandatory).
 
-## Branch protection on `main`
-
-No direct push, no force-push, no deletion; every change is a PR with ≥1 Habilité
-(CODEOWNERS) approval, passing checks (`lefthook (framework-local checks)`,
-`Commitlint`), and resolved threads. Machine-readable form:
-[`.github/rulesets/main.json`](.github/rulesets/main.json) (enforced once the repo
-is public / on a paid plan).
+## Branch protection on `main` and `next`
+
+`main` is production: no direct push, no force-push, no deletion; every change is
+a PR with ≥1 Habilité (CODEOWNERS) approval, passing checks (`lefthook
+(framework-local checks)`, `Commitlint`), and resolved threads. Machine-readable
+form: [`.github/rulesets/main.json`](.github/rulesets/main.json) (enforced once
+the repo is public / on a paid plan).
+
+`next` is the integration branch: PRs and passing checks, no direct push or
+deletion, but no required review so the week's work batches quickly. The release
+bot bypasses to push the automated back-merge. Machine-readable form:
+[`.github/rulesets/next.json`](.github/rulesets/next.json). The release flow is in
+[`RELEASE.md`](RELEASE.md).
 
 ## Code of Conduct & amendments
 

diff --git a/RELEASE.md b/RELEASE.md
@@ -0,0 +1,74 @@
+# Release
+
+How the AI-Driven Dev Framework ships, and what to follow when you open a
+change. Weekly rolling releases, with a fast lane for urgent fixes.
+
+For branch naming, commit format, and the release tooling, see [`aidd_docs/memory/vcs.md`](aidd_docs/memory/vcs.md).
+
+For who may merge and release, see [`GOVERNANCE.md`](GOVERNANCE.md).
+
+## Principle
+
+- `main` is production. The marketplace tracks it, so users only ever get
+  released, versioned code.
+- `next` is integration. The week's work batches here, and ships in one weekly
+  release.
+- A release happens only when there is work, and is cut automatically by
+  release-please.
+- A `hotfix/*` skips `next`: it branches from `main` and ships its own release
+  out of cycle, for urgent production fixes.
+
+## 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`.
+
+```mermaid
+flowchart LR
+    work["feat/* · fix/* · docs/* · …"] -->|PR| next
+    next -->|weekly promotion PR| main
+    main -->|release-please PR, auto-merged| rel["tag + version bump"]
+    rel -->|back-merge, auto| next
+    hotfix["hotfix/*"] -->|PR| main
+```
+
+Two merges reach `main`: the weekly promotion PR from `next`, then the
+auto-merged Release PR that release-please raises.
+
+## What your commit produces
+
+The commit type drives the changelog section it lands under.
+
+| Commit type | Changelog section |
+| ----------- | ----------------- |
+| `feat`      | Features          |
+| `fix`       | Bug Fixes         |
+| `perf`      | Performance       |
+| `refactor`  | Refactoring       |
+| `docs`      | Documentation     |
+| `chore`     | Miscellaneous     |
+| `revert`    | Reverts           |
+
+The version bump is release-please's call: `feat` → minor, `fix` → patch, a `!`
+suffix or `BREAKING CHANGE` footer → major. The other types ride along in a
+release triggered by a `feat` or `fix`.
+
+## The two rules that keep it safe
+
+- **The Release PR is auto-merged.** Otherwise `main` briefly holds merged but
+  unversioned code, and a new user installing in that window picks it up.
+- **The `main` → `next` back-merge is automatic.** Otherwise the version
+  manifest and the changelog on `next` drift from `main`.
+
+## Weekly release, step by step
+
+1. Open the promotion PR `next` → `main` once the week's work is ready.
+2. release-please opens a Release PR on `main`; it is auto-merged.
+3. Tags and version bumps are created; release artifacts are attached.
+4. `main` is back-merged into `next` automatically.
+
+## Hotfix
+
+1. Branch `hotfix/*` from `main`, fix, PR back to `main`.
+2. release-please cuts a dedicated patch release.
+3. `main` is back-merged into `next` automatically.
diff --git a/aidd_docs/brainstorm/2026_06_19-rolling-weekly-releases.md b/aidd_docs/brainstorm/2026_06_19-rolling-weekly-releases.md
@@ -0,0 +1,48 @@
+# Rolling weekly releases
+
+> Brainstorm — 2026-06-19. Idée consolidée, niveau intention. Pas de plan ni de code.
+
+## L'idée
+
+Shipper le framework chaque semaine, vite et de façon cadencée, tout en gardant une norme de branches qui permet les hotfix — sans qu'un nouvel utilisateur reçoive jamais du code non-versionné.
+
+Le framework est un monorepo de plugins distribué via une marketplace : les utilisateurs suivent la branche par défaut du repo à son sommet. Aujourd'hui les features arrivent directement sur cette branche, donc un nouvel utilisateur qui installe récupère du code fusionné mais pas encore publié, sous un ancien numéro de version. C'est le défaut à corriger.
+
+## Faits qui cadrent la décision
+
+- Le numéro de version d'un plugin sert de clé de cache : sans incrément, un utilisateur déjà installé ne reçoit rien.
+- La marketplace suit la branche par défaut à son sommet ; un nouvel utilisateur prend donc l'état courant de cette branche, versionné ou non.
+- Pour une marketplace tierce, la mise à jour automatique est désactivée par défaut côté utilisateur.
+- La résolution de version prend le numéro porté par le plugin en premier.
+
+## La forme retenue
+
+Deux branches : une branche de **production** (celle que suivent les utilisateurs, qui ne doit contenir que du publié) et une branche d'**intégration** où s'accumulent les features de la semaine.
+
+- Les features et corrections passent par l'intégration.
+- Quand c'est prêt, l'intégration est promue vers la production, ce qui déclenche une publication versionnée **fusionnée automatiquement**, puis une remontée **automatique** de la production vers l'intégration pour resynchroniser.
+- Un hotfix part de la production, y revient en publication dédiée hors cadence, puis est remonté vers l'intégration.
+
+Le gestionnaire de versions existant est conservé et reste la source de l'incrément.
+
+Alternative écartée : faire surveiller au gestionnaire de versions la branche d'intégration puis fast-forward vers la production. Garantit une production mathématiquement pure (zéro fenêtre d'exposition) mais impose un double suivi et une remontée fragile — complexité jugée supérieure au bénéfice.
+
+## Contraintes non négociables
+
+- La publication versionnée doit être fusionnée automatiquement. Sinon, entre la promotion et la publication, la production contient des features non versionnées et un nouvel utilisateur les capte. L'auto-fusion réduit cette fenêtre à la durée d'un passage d'intégration continue.
+- La remontée production → intégration doit être automatique, sinon les états de version et de journal divergent.
+
+## Risque résiduel assumé
+
+Une fenêtre d'exposition de l'ordre d'un passage d'intégration continue subsiste, une fois par semaine, sur une petite base d'utilisateurs. Jugée négligeable au regard de la simplicité gagnée.
+
+## Assumptions ouvertes (à confirmer à l'étape suivante)
+
+- **Où tourne le gestionnaire de versions aujourd'hui** : aucun workflow d'automatisation dans le module `framework/` lui-même ; il tourne probablement à la racine du monorepo parent. À vérifier avant toute modification.
+- **Nom de la branche d'intégration** : `next` envisagé, renommable.
+- **Cohérence des numéros embarqués dans le manifeste de marketplace** : aujourd'hui figés et divergents des numéros réels des plugins. À nettoyer pour une source unique.
+- **Cadence stricte vs opportuniste** : publication seulement s'il y a eu du travail dans la semaine.
+
+## Prochaine étape
+
+L'idée est mûre pour une **planification technique** : traduire ce modèle de branches en automatisations concrètes (promotion, auto-fusion de la publication, remontée, protections de branches), documenter le flux de contribution, et vérifier d'abord où l'automatisation de version s'exécute réellement.