cohorte 2.0.2 → 2.1.0

package/CHANGELOG.md

@@ -7,6 +7,34 @@ short, user-facing, most recent first. One `## <version> — <YYYY-MM-DD>` secti
 > They are history and are deliberately not rewritten — every command gained a `cohorte-` prefix
 > in 2.0.0.
 
+## 2.1.0 — 2026-08-09
+
+- **A repo that gates merges on a per-feature release note shipped red PRs, and the flow reported
+  success.** Changesets' `changeset` job fails any PR that touches product code without a
+  `.changeset/*.md`, but that requirement lives in the project's `CLAUDE.md` — which the ship flow
+  never reads. So `/cohorte-ship` committed, pushed, opened the PR and moved the kanban card to
+  **Shipped** while the PR was unmergeable, red on a job nobody was watching.
+
+  The profile gains a `release_notes` block (`enabled`, `tool`, `dir`/`filename`,
+  `anchor_package`, `language`, `forbid_levels`, `empty_cmd`, `ci_job`, `guidance` — SCHEMA.md
+  §Release notes), and `/cohorte-ship` gains **§2b**: the lead writes the note itself, next to the
+  `status: shipped` flip, so it lands *inside* the release commit rather than in a second one after
+  the PR is already open. The bump level is project policy, not a git ritual — the release agent is
+  now explicitly forbidden from authoring or editing a note, and only stages the one it is handed.
+  §4 verifies the note is in the commit; §5 routes a red `ci_job` back to §2b instead of through
+  `/cohorte-fix`, which would treat a missing note as a code finding.
+
+  Two things the block encodes that the tool itself does not: `forbid_levels`, for the `0.x` repo
+  where a `major` changeset silently jumps to `1.0.0` with no human deciding it, and the rule to
+  **ask** rather than guess between two defensible levels — a wrong bump is a published version
+  number, not a fixable draft. `empty_cmd` covers the honest no-op, for a PR that must move no
+  version at all.
+
+- **Existing projects are asked, not defaulted.** `/cohorte-init-pipeline` detects a versioning tool
+  or note-enforcing CI job in Phase 1 and asks the anchor package, language and bump policy in Phase
+  2; `/cohorte-update-pipeline` treats `release_notes` as a genuine human decision during reconcile
+  rather than topping it up blind. No tool found ⇒ `enabled: false`, and §2b is a silent no-op.
+
 ## 2.0.2 — 2026-08-08
 
 - **Kanban cards stopped moving mid-pipeline, and every stage still reported success.** The

package/core/agents/release.md

@@ -23,11 +23,17 @@ committing, pushing, and opening the PR. You do **not** write features.
   on pushed commits), or delete branches.
 - Run anything in `PIPELINE.md` §`gate.deny` (destructive DB/history).
 - Commit secrets — inspect `git status`/`git diff` and refuse if `.env` or credentials are staged.
+- **Author or edit a release note** (`.changeset/*.md` or whatever `PIPELINE.md` §`release_notes`
+  declares). The lead writes it before dispatching you; picking a bump level is project policy, not a
+  git ritual. You only **stage** it. If `release_notes.enabled` and the file is absent, say so in your
+  report instead of inventing one — the lead fixes it.
 
 ## Your inputs
 
 1. The spec path `specs/<id>.md` (title, goal, contract — for the PR body).
 2. `feature_id` and the branch `<vcs.feature_branch_prefix><id>`.
+3. If `PIPELINE.md` §`release_notes.enabled`, the already-written note at
+   `<release_notes.dir>/<release_notes.filename>` — stage it with everything else.
 
 ## Steps
 

package/core/commands/cohorte-ship.md

@@ -6,7 +6,9 @@ argument-hint: <feature_id>
 
 You are the **lead**. Ship feature **$ARGUMENTS**. This is the outward-facing gate.
 
-> Read `PIPELINE.md` §`vcs` (host, remote, default_branch, feature_branch_prefix).
+> Read `PIPELINE.md` §`vcs` (host, remote, default_branch, feature_branch_prefix) **and
+> §`release_notes`** — §2b below is skipped or required based on it, and skipping it when it is
+> required opens a PR that CI fails on arrival.
 >
 > **Kanban** (SCHEMA.md §Kanban) is mirrored in **explicit steps** below, not as an afterthought:
 > §1 moves the card → **Ship**; §4 moves it → **Shipped** and writes the PR number. Both are one
@@ -41,19 +43,50 @@ Once the human confirms, edit `specs/$ARGUMENTS.md` front-matter `status: → sh
 dispatching the release agent, so the status flip is part of the tree it commits (otherwise it lands
 uncommitted after the PR opens). Only flip after the human's "yes"; if they decline, leave it.
 
+## 2b. Write the release note (only if `release_notes.enabled` — same reason: it must ship in the commit)
+
+`release_notes.enabled: false` (or `tool: none`) ⇒ skip this section entirely, silently.
+
+Otherwise **you** write it — never the release agent, never the implementers. Picking the bump is
+project policy and the prose is outward-facing copy; both are the lead's, exactly like the contract.
+See SCHEMA.md §Release notes.
+
+- Write `<release_notes.dir>/<release_notes.filename>` (`<feature_id>` substituted), front-matter
+  carrying the **single** key `release_notes.anchor_package` and the chosen level, then the prose body
+  in `release_notes.language`.
+- **Choose the level** against `release_notes.guidance`, and refuse any level in
+  `release_notes.forbid_levels` (a `0.x` repo forbidding `major` declares the rupture `minor`).
+- **Ambiguous between two defensible levels?** State your reading in one line and **ask the human to
+  pick** before writing. A wrong bump becomes a published version number.
+- The body describes what changed **for the user**, from the spec §1/§2 — no client names, no internal
+  paths, no exploitable attack vector, no file lists.
+- If the feature genuinely must move no version, use `release_notes.empty_cmd` instead. Prefer that to
+  skipping: the CI job wants a file, not a version.
+- Then say in one line which level you chose and why — this is the human's last chance to correct it
+  before it is committed.
+
+> **Why this is its own gate.** The requirement usually lives in the project's `CLAUDE.md`, which this
+> flow never reads. Skip it and everything below still "succeeds": commit, push, PR opened, kanban card
+> moved to **Shipped** — and CI red on a job nobody watched. The feature reads as shipped while being
+> unmergeable.
+
 ## 3. Dispatch the `release` agent
 
 Spawn one agent (`subagent_type: release`): "Release feature `$ARGUMENTS` on branch
 `<feature_branch_prefix>$ARGUMENTS`. Read `PIPELINE.md` §vcs first. Spec: `specs/$ARGUMENTS.md` (already
 `status: shipped` — stage it). Write conventional commit(s), push (no force), open the PR (use `gh` if
 `host: github` + available; else emit the compare URL + drafted PR body from `.claude/templates/pr-body.md`).
-Stage **all** the feature's changes including `specs/$ARGUMENTS.md`. Never edit source, never force-push,
-never run migrations."
+Stage **all** the feature's changes including `specs/$ARGUMENTS.md` and, if `release_notes.enabled`, the
+release note at `<release_notes.dir>/<release_notes.filename>` — it is already written, stage it as-is and
+never author or edit one yourself. Never edit source, never force-push, never run migrations."
 
 ## 4. Relay + move the card to Shipped (do not skip)
 
 Print the release agent's report: commit SHA(s), pushed branch, PR URL (or compare URL + drafted body).
-Confirm `specs/$ARGUMENTS.md` was committed as `status: shipped` (part of the release commit).
+Confirm `specs/$ARGUMENTS.md` was committed as `status: shipped` (part of the release commit), and — if
+`release_notes.enabled` — that the release note is in that same commit
+(`git show <sha> --stat | grep <release_notes.dir>`). Missing ⇒ commit and push it now, before §5's CI
+watch, rather than letting the job go red.
 
 **Move the card to Shipped — required, and verify it actually moved.** Run
 `<core>/pipeline/scripts/kanban-move.sh auto $ARGUMENTS shipped --pr <num>`, which **appends the PR
@@ -78,7 +111,9 @@ call. Silent no-op without consent; never ask about consent here.
 ## 5. After the PR — CI gate + teardown
 
 - If `host: github` and `gh` is available, watch the PR's checks (`gh pr checks <url> --watch`) and
-  report the result — the human merges only on green. A red check ⇒ back to `/cohorte-fix $ARGUMENTS`.
+  report the result — the human merges only on green. A red check ⇒ back to `/cohorte-fix $ARGUMENTS`,
+  **except** a red `release_notes.ci_job`: that one is this command's own miss, not a code finding —
+  write the note per §2b, commit, push, and re-watch. Never send a missing release note through `/cohorte-fix`.
 - Once the human confirms the PR is **merged**: if `isolation.enabled`, propose the teardown —
   `scripts/remove-feature.sh $ARGUMENTS` (add `--drop-db` to also drop the feature db; kept by
   default). It removes the worktree, deletes the merged branch, frees the slot. Never run it before

package/core/templates/steps/init-pipeline/01-detect-stack.md

@@ -24,6 +24,10 @@ Gather evidence, then summarize what you found. Look for:
   `package.json` scripts + the workspace filter syntax (e.g. `pnpm --filter <pkg> test`).
 - **Contract mechanism:** a shared types/schema package (`packages/shared-types`, Zod/`z.`),
   an `openapi.*`/`swagger.*` file, `.proto` files, or none.
+- **Release notes / versioning:** a `.changeset/` directory (+ `config.json`, and whether it declares a
+  `fixed`/lockstep group — that names the anchor package), `changesets` in devDependencies, or a CI job
+  that fails a PR lacking a note (grep `.github/workflows/*` for `changeset`). Also note the root
+  `version`: a `0.y.z` product usually forbids `major`. None of these ⇒ `release_notes.enabled: false`.
 - **DB / migrations:** migration tooling (`node ace make:migration`, `knex`, `prisma`, `alembic`,
   `golang-migrate`), a `docker-compose.yml`, DB service.
 - **Design system:** an existing `design-reference/` snapshot, `components/ui`, a DesignSync MCP
@@ -36,5 +40,5 @@ Gather evidence, then summarize what you found. Look for:
 - **Existing `CLAUDE.md`** — read it; it may already state stack/conventions to fold in. **Existing
   `PIPELINE.md`** — if present, this is a re-run: load it as the starting draft and only reconcile deltas.
 
-Print a compact **Detection Report**: layout, surfaces (with framework + commands), contract, DB,
-design, vcs. Mark each field `detected` / `guessed` / `unknown`.
+Print a compact **Detection Report**: layout, surfaces (with framework + commands), contract, release
+notes, DB, design, vcs. Mark each field `detected` / `guessed` / `unknown`.

package/core/templates/steps/init-pipeline/02-interview-gaps.md

@@ -24,6 +24,12 @@ Ask ONLY what you couldn't confidently detect. Batch related questions. Cover:
   the runner has no such flag, leave `""` — consumers then fall back to `<cmd> 2>&1 | tail -40`.
 - **Contract** — mechanism (`shared-types-zod` / `openapi` / `protobuf` / `json-schema` / `none`) and
   where feature contracts are authored. If `none`, surfaces sync by the spec prose alone.
+- **Release notes (only if Phase 1 found a versioning tool or a note-enforcing CI job)** — confirm the
+  anchor package (a `fixed`/lockstep group means ONE key propagates to all), the note's language, and the
+  **bump policy** the lead will apply at `/cohorte-ship`: what counts as major/minor/patch here, and
+  whether any level is forbidden (a `0.y.z` product normally forbids `major` — Changesets would jump it
+  to `1.0.0` with no human deciding). Policy prose lands in `release_notes.guidance`. Nothing detected ⇒
+  don't ask; leave `release_notes.enabled: false`.
 - **UI language** — language of all user-facing copy.
 - **RBAC** — is there a role hierarchy? If yes, list it highest→lowest.
 - **Design system** — enabled? provider (Claude Design / Figma / none) + project ids + kit/token paths.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cohorte",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "description": "Portable, stack-agnostic multi-agent development pipeline for Claude Code — install the core, run /cohorte-init-pipeline, and it adapts to your project's stack.",
   "bin": {
     "cohorte": "bin/cli.js"

package/profile/PIPELINE.template.md

@@ -97,6 +97,26 @@ contract:
   index: packages/shared-types/src/index.ts   # barrel to export from, or "" if none
   authored_by: lead                           # NEVER the implementer agents
 
+# ── release notes (optional) ────────────────────────────────────────────────
+# A per-feature release note the project's versioning tool consumes. When
+# enabled, /cohorte-ship authors it BEFORE dispatching the release agent, so it
+# ships inside the release commit. Repos whose CI fails a PR that lacks one
+# (Changesets' `changeset` job) MUST set this — otherwise every ship goes red.
+release_notes:
+  enabled: <true | false>                     # false ⇒ /cohorte-ship §2b is a no-op
+  tool: <changesets | none>                   # what consumes the file
+  dir: .changeset                             # where the note is authored
+  filename: "<feature_id>.md"                 # one file per feature
+  anchor_package: shared-types                # sole key in the front-matter; a lockstep/fixed group propagates the bump
+  language: <ui_language | English>           # language of the note's prose
+  forbid_levels: []                           # bumps project policy refuses, e.g. [major] while 0.x
+  empty_cmd: "pnpm changeset --empty"         # when no version should move; "" if the tool has no such escape hatch
+  ci_job: changeset                           # CI job that fails when the note is missing (name it so /cohorte-ship §5 recognizes the red)
+  guidance: |                                 # rules the lead follows when writing the note (project policy)
+    major = the deploy needs an operator action; minor = a user-visible capability;
+    patch = fix/perf/refactor with no change of use. No client names, no internal
+    paths, no exploitable attack vector.
+
 # ── repo-wide commands (root unless noted) ──────────────────────────────────
 commands:
   install: pnpm install

package/profile/SCHEMA.md

@@ -33,6 +33,15 @@ generic pipeline uses it, so a stateless agent can read/regenerate the profile c
 | `contract.mechanism`                 | enum         | build, lead                       | `shared-types-zod`/`openapi`/`protobuf`/`json-schema`/`none`. |
 | `contract.path` `.ext` `.index`      | string       | build                             | Where `<feature_id>` contract is authored + barrel.           |
 | `contract.authored_by`               | const `lead` | build                             | Implementers import it read-only, never edit.                 |
+| `release_notes.enabled`              | bool         | ship                              | `false` ⇒ skip note authoring (§2b of /cohorte-ship). See §Release notes. |
+| `release_notes.tool`                 | enum         | ship                              | `changesets`/`none` — what consumes the file.                 |
+| `release_notes.dir` `.filename`      | string       | ship                              | Where the per-feature note is authored, e.g. `.changeset/<feature_id>.md`. |
+| `release_notes.anchor_package`       | string       | ship                              | Sole key in the note's front-matter; a lockstep/`fixed` group propagates the bump. |
+| `release_notes.language`             | string       | ship                              | Language of the note's prose — usually `ui_language`.         |
+| `release_notes.forbid_levels`        | list         | ship                              | Bump levels project policy refuses, e.g. `[major]` while `0.x`. |
+| `release_notes.empty_cmd`            | string       | ship                              | Escape hatch when no version should move; `""` if none.       |
+| `release_notes.ci_job`               | string       | ship                              | CI job that fails on a missing note — lets §5 name the red check. |
+| `release_notes.guidance`             | string       | ship                              | Project policy the lead follows when picking the bump + writing the prose. |
 | `commands.*`                         | string       | all                               | Repo-wide install/dev/lint/format/typecheck/test + migrate.   |
 | `commands.test_quiet` `.lint_quiet`  | string       | review, audit, workflows          | Repo-wide bridled variants — what the `/cohorte-review` pre-flight runs. Same fallback as the per-surface ones. |
 | `rbac.enabled`                       | bool         | brainstorm, review                | Toggle RBAC personas + authz audit.                           |
@@ -412,6 +421,36 @@ this exact procedure so a surface is always defined the same way. To add surface
 Removing/merging a surface is the reverse: drop the `surfaces[]` entry, delete its agent file, fold its
 conventions. Never leave an agent file with no matching `surfaces[]` entry (orphan) or vice-versa.
 
+## Release notes — the per-feature note the versioning tool consumes
+
+Many repos gate merges on a **per-feature release note**: Changesets' `changeset` CI job fails any PR
+that touches product code without a `.changeset/*.md`. That file is **not** something the release
+agent can invent — picking the bump level is project policy (semver over an API vs. over a product,
+a `0.x` rule forbidding `major`, what counts as user-visible), and the prose is outward-facing copy.
+It is the **lead's** to write, exactly like the contract.
+
+The failure mode this block exists to prevent is silent and reproducible: the requirement lives in the
+project's `CLAUDE.md`, which the ship flow never reads, so `/cohorte-ship` completes, opens the PR,
+moves the kanban card to **Shipped** — and CI goes red on a job nobody looked at. The feature reads as
+shipped while being unmergeable. Encoding it in the profile is what makes the step survive a stateless
+lead.
+
+- **Authored before the dispatch**, next to the `status: shipped` flip (`/cohorte-ship` §2b), so the note
+  lands **inside** the release commit. Written after the fact it needs a second commit, and the PR is
+  already open and red.
+- **One key in the front-matter** — `anchor_package`. Lockstep/`fixed` version groups propagate the bump
+  from it to every other workspace; listing more is how a repo ends up with a package bumped twice.
+- **`forbid_levels`** encodes policy the tool itself may not enforce. The common one: while the product
+  is `0.y.z`, a `major` changeset makes Changesets jump to `1.0.0` with no human deciding it — so `0.x`
+  repos forbid `major` and declare a breaking change as `minor`.
+- **Ask, don't guess, on an ambiguous bump.** Between two defensible levels (a refactor that also changes
+  what the user sees), state the reading and let the human pick — a wrong bump is a published version
+  number, not a fixable draft.
+- **`empty_cmd`** covers the honest no-op: a PR that touches product code but must move no version.
+  Prefer it to skipping the step; the CI job wants a file, not a version.
+
+`enabled: false` (or `tool: none`) ⇒ §2b is a no-op and nothing below applies.
+
 ## Reconcile — bringing generated files up to the current core
 
 `/cohorte-init-pipeline` is **one-time per project**. Afterwards, `/cohorte-update-pipeline` runs this procedure so a
@@ -423,7 +462,10 @@ files automatically. It works because every generated artifact is a **determinis
    `pipeline/PIPELINE.template.md`: every block/field the template has and the profile lacks is added
    with its documented default (e.g. `surfaces[].model: sonnet`, `retrieval.provider: serena`).
    **Ask only when a new field is a genuine human decision** (batch into ONE question set); never
-   change a value the profile already sets; never rewrite the prose sections.
+   change a value the profile already sets; never rewrite the prose sections. `release_notes` is one
+   such decision and must not be defaulted blind: detect a versioning tool / note-enforcing CI job per
+   `/cohorte-init-pipeline` Phase 1, and if there is one, ask Phase 2's release-notes question (anchor
+   package, language, bump policy, forbidden levels). No tool found ⇒ top up with `enabled: false`.
 2. **Re-render agent frontmatter + body.** For each `surfaces[]` entry, re-render
    `.claude/agents/<agent>.md` from the current `implementer.template.md` per §Rendering above. Safe by
    doctrine: rendered agents are regenerable artifacts — hand-written rules belong in `PIPELINE.md`