cohorte 2.0.1 → 2.1.0

package/CHANGELOG.md

@@ -7,6 +7,82 @@ 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
+  stages only *described* the move — "move card `#<id>` → Building, no-op silently if no board" —
+  without saying where a board is even declared. Each phase runs in its own session after a
+  `/clear`, so the cheapest reading consistent with that instruction is "I see no board, so there
+  is none": a `/cohorte-ship` run announced "no kanban board configured", having opened neither
+  `~/.claude/cohorte.config.yaml` nor `PIPELINE.md`, and a feature that shipped and merged left
+  its card sitting in "Ready to build". Silence was indistinguishable from correctness, so this
+  went unnoticed across several features.
+
+  Resolution is not a judgment call, so it is no longer made by a judge. `kanban-move.sh auto <id>
+  <stage>` now reads the profile `name`, the config's `kanban.enabled` / `obsidian.vault_path` /
+  `boards[name]`, and maps the **stage key** (`ideas` … `shipped`) to that board's heading through
+  `boards[name].columns` → `kanban.columns` → a built-in default. Every stage calls exactly that,
+  and reports the line it printed: `moved #<id> -> <column>`, or `kanban: <reason>` naming the
+  missing link. Both exit 0 and they are not interchangeable. A board that *is* configured but
+  unmovable stays loud (exit 2 usage, exit 3 missing board / unknown column). Explicit board paths
+  and literal headings still work.
+
+  `validate-core` now fails any funnel command that moves a card without a literal
+  `kanban-move.sh auto …` call, or that omits the instruction not to conclude "no board" without
+  running it — the prose-only form is what regressed, so the prose-only form is what is banned.
+  New `scripts/test-kanban.mjs` (29 checks) pins the resolution table and the move semantics.
+
+- **Renaming a project silently unlinks its board.** `kanban.boards` is keyed by the profile
+  `name`, so editing `name:` orphans the old entry and no lookup matches the new one — a genuine
+  "not configured", identical from the outside to never having had a board. `/cohorte-doctor`
+  gains check **7b**, which reports the resolved board (or the exact missing link) and flags an
+  orphaned entry as a rename; `/cohorte-update-pipeline` offers to re-key it instead of creating a
+  second board. New `kanban-move.sh --check` does the resolution alone, for both.
+
+- **The gate judged `cd <other repo> && git commit` against the wrong checkout.** Branch-conditional
+  patterns resolved the branch at the payload cwd, but the tool's shell keeps no cwd between calls,
+  so agents write the `cd` into the command itself. A commit on a feature branch in another repo was
+  therefore refused as if it were on the default branch — and the refusal named a branch the command
+  was never going to run on, so no confirmation could lift it (in an unattended run, where `ask`
+  escalates to `deny`, it was a hard wall). The branch is now resolved per segment at the cwd that
+  segment actually runs in, cached so the common case is still one `git` call. Deliberately narrow:
+  a plain absolute/relative/quoted `cd`, never `cd -`, `$(…)`, variables or globs — anything
+  unresolvable keeps the previous cwd, which is the direction that keeps gating. `cd` never softens
+  the unconditional `deny`/`ask` tiers; 10 new cases in `test-gate.mjs` pin all of it.
+
+- **`/cohorte-brainstorm` tags an Ideas card before moving it.** The join key is the `#<id>` tag,
+  and an Ideas card a human typed by hand has none — so the move found nothing, created a second
+  card, and stranded the original in Ideas. It now appends the tag first, located by `grep -n`,
+  never a full board read.
+
 ## 2.0.1 — 2026-08-03
 
 Three fixes, one failure: an autonomous `/cohorte-loop` run that built 1 surface of 3, stamped

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-brainstorm.md

@@ -20,8 +20,13 @@ at Finish, when a board is configured.
 > Template paths below (`.claude/templates/…`) resolve to `~/.claude/templates/…` when the core is
 > installed globally — read whichever exists.
 >
-> **Kanban** (SCHEMA.md §Kanban): resolve this project's board from `~/.claude/cohorte.config.yaml`
-> `kanban.boards[<PIPELINE name>]`. Everything kanban below no-ops silently if none resolves.
+> **Kanban** (SCHEMA.md §Kanban): every card move below is one call —
+> `<core>/pipeline/scripts/kanban-move.sh auto <feature_id> <stage> [--title "<human title>"]`, with
+> `<core>` = `.claude` bundled / `~/.claude` global (probe with `test -x`). `auto` resolves the
+> board from `~/.claude/cohorte.config.yaml` itself and exits 0 with a `kanban: <reason>` line when
+> none resolves — so **never decide "no board is configured" without running it**. Reading the Ideas
+> column at Start still needs the board path: get it from a `kanban-move.sh` run, or grep the config
+> for `boards[<PIPELINE name>]`.
 
 Idea (may be empty): **$ARGUMENTS**
 
@@ -52,9 +57,16 @@ when invoked with no paste). In chat print only a 3-line summary + the path. Tel
 — **recommend a `/clear` first**, the return is staged on disk (pasting it remains a fallback).
 
 **Kanban:** settle the `feature_id` (kebab-case slug) the return carries — it is the card's join key
-downstream. If a board is configured, **move** the card into the **Brainstorm** column tagged
-`#<feature_id>` (per §Kanban): the picked Ideas card if the human chose one, else a new card. No-op if
-no board.
+downstream. Then, in this order:
+
+1. **If the human picked an Ideas card, tag it first.** Ideas cards are free text a human typed, with
+   no `#<feature_id>` on them, and the move script joins on that tag: move before tagging and it
+   finds nothing, creates a second card, and leaves the untagged original sitting in Ideas forever.
+   One targeted Edit appending `  #<feature_id>` to that line, located by `grep -n`, never a full
+   board read.
+2. `<core>/pipeline/scripts/kanban-move.sh auto <feature_id> brainstorm --title "<human title>"` —
+   which moves the (now tagged) card, or creates one under `--title` if the human typed a fresh
+   idea. Read its output: `moved #…` or `kanban: <reason>`. Never assume either.
 
 **Telemetry:** chain the opt-in usage ping onto that same Bash call — `/cohorte-build` §4's shared form,
 `<phase>` = `brainstorm`, `<seconds>` = `0` (this phase is human thinking time, not pipeline

package/core/commands/cohorte-build.md

@@ -10,8 +10,12 @@ You are the **lead**. Build feature **$ARGUMENTS** from its frozen spec.
 > dispatch + their agent names), `contract` (mechanism + path), and the `design` flag. _Skip the
 > re-read if it's already in your context this session and unmodified since._
 >
-> **Kanban** (SCHEMA.md §Kanban): once §1 confirms the frozen spec, move card `#$ARGUMENTS` →
-> **Building**. No-op silently if no board is configured.
+> **Kanban** (SCHEMA.md §Kanban): once §1 confirms the frozen spec, run
+> `<core>/pipeline/scripts/kanban-move.sh auto $ARGUMENTS building` (`<core>` = `.claude` bundled /
+> `~/.claude` global — probe with `test -x`). `auto` resolves the board from the config itself and
+> exits 0 with a `kanban: <reason>` line when there is none — so **never decide "no board is
+> configured" without running it**. That inference, not a missing board, is what used to freeze
+> cards mid-pipeline.
 
 ## 1. Load & check
 

package/core/commands/cohorte-doctor.md

@@ -76,6 +76,15 @@ fix only with the human's go-ahead (or hand them the command).
    incoherent state: `enabled: true` with no `install_id` or no `consent_date` (sending without
    recorded consent — fix: set `enabled: false` until the consent question is re-run), or a
    `telemetry:` block missing entirely on a current core (top up via `/cohorte-update-pipeline`).
+7b. **Kanban** (the board mirror — SCHEMA.md §Kanban). Run
+   `<core>/pipeline/scripts/kanban-move.sh --check` and report its one line verbatim: the resolved
+   board path, or the exact link that is missing. A board mirror is optional, so "not configured" is
+   ℹ️, never ❌ — but it must be **stated**, because the whole class of bug here is a card that
+   quietly stopped moving while every command still reported success. Two states earn a ⚠️ with the
+   fix named: `boards` has no entry for this profile's `name` while it does have an entry for some
+   other key whose board file exists (a **rename** orphaned the link — re-key it via
+   `/cohorte-update-pipeline`), and an entry whose board file no longer exists at
+   `vault_path`-relative `board` (moved or renamed in the vault).
 8. **Workflows** (the opt-in execution path — SCHEMA.md §Workflows; the conversational commands
    stay the default, so failures here are ⚠️ at most, never ❌). Report which path this machine will
    take and why:

package/core/commands/cohorte-fix.md

@@ -11,8 +11,11 @@ that change the *contract*; `/cohorte-fix` is for everything else.
 > Read `PIPELINE.md` §`pipeline-profile` first: `surfaces` (paths + agent names) and `contract`.
 > _Skip the re-read if it's already in your context this session and unmodified since._
 >
-> **Kanban** (SCHEMA.md §Kanban): move card `#$ARGUMENTS` → **Fix** on ingest (it returns to **Review**
-> when `/cohorte-review` re-runs). No-op silently if no board.
+> **Kanban** (SCHEMA.md §Kanban): on ingest, run
+> `<core>/pipeline/scripts/kanban-move.sh auto $ARGUMENTS fix` (`<core>` = `.claude` bundled /
+> `~/.claude` global — probe with `test -x`); the card returns to **Review** when `/cohorte-review`
+> re-runs. `auto` resolves the board from the config itself and exits 0 with a `kanban: <reason>`
+> line when there is none — so **never decide "no board is configured" without running it**.
 
 ## 1. Ingest the report
 

package/core/commands/cohorte-review.md

@@ -9,7 +9,11 @@ You are the **lead**. Dispatch the review for feature **$ARGUMENTS**.
 > Read `PIPELINE.md` §`vcs.default_branch` (diff base) and the `surfaces`/`contract`/`commands` fields.
 > _Skip the re-read if it's already in your context this session and unmodified since._
 >
-> **Kanban** (SCHEMA.md §Kanban): move card `#$ARGUMENTS` → **Review**. No-op silently if no board.
+> **Kanban** (SCHEMA.md §Kanban): run
+> `<core>/pipeline/scripts/kanban-move.sh auto $ARGUMENTS review` (`<core>` = `.claude` bundled /
+> `~/.claude` global — probe with `test -x`). `auto` resolves the board from the config itself and
+> exits 0 with a `kanban: <reason>` line when there is none — so **never decide "no board is
+> configured" without running it**.
 >
 > **Workflow variant** (opt-in — SCHEMA.md §Workflows): on Claude Code ≥ 2.1.154 with workflows
 > enabled, the human can ask to "run the review workflow" (`<core>/workflows/review.js`) instead.

package/core/commands/cohorte-ship.md

@@ -6,12 +6,17 @@ 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. No-op silently if
-> no board. Do not skip §4's move — a shipped feature whose card is stuck in an earlier column is the
-> bug this ordering prevents.
+> §1 moves the card → **Ship**; §4 moves it → **Shipped** and writes the PR number. Both are one
+> call to `<core>/pipeline/scripts/kanban-move.sh auto …` (`<core>` = `.claude` bundled / `~/.claude`
+> global — probe with `test -x`), which resolves the board from the config itself and exits 0 with a
+> `kanban: <reason>` line when there is none. **Never decide "no board is configured" without running
+> it** — a ship session that inferred that, having opened neither the config nor `PIPELINE.md`, is
+> exactly how a merged feature's card stayed in "Ready to build". Do not skip §4's move either.
 
 ## 1. Pre-flight (confirm before doing anything irreversible)
 
@@ -29,7 +34,8 @@ You are the **lead**. Ship feature **$ARGUMENTS**. This is the outward-facing ga
   All `- [x]` ⇒ proceed silently.
 - Show `git status` + `git diff --stat`; confirm the branch is `<feature_branch_prefix>$ARGUMENTS`.
 - **Ask the human to confirm** they want to commit, push, and open the PR. Wait for yes.
-- After the yes: **move card `#$ARGUMENTS` → the `ship` column** (SCHEMA.md §Kanban "Move a card"). No-op if no board.
+- After the yes: `<core>/pipeline/scripts/kanban-move.sh auto $ARGUMENTS ship`. Report what it
+  printed — `moved #…` or `kanban: <reason>` — never a guess about which happened.
 
 ## 2. Mark the spec shipped (BEFORE dispatch, so it ships in the same commit)
 
@@ -37,28 +43,63 @@ 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
+number** so the line reads `- [ ] <title> #$ARGUMENTS — PR #<num>`. Take `<num>` from the PR URL
+(`…/pull/13` ⇒ `13`); **always pass it when a PR was created** (the `gh` path) — it is what the
+dashboard turns into a PR link. If only a compare URL was emitted (no PR yet), drop `--pr`.
 
-**Move the card to Shipped — required, and verify it actually moved.** Move card `#$ARGUMENTS` → the
-`shipped` column (SCHEMA.md §Kanban "Move a card") and **append the PR number** so the line reads
-`- [ ] <title> #$ARGUMENTS — PR #<num>`. Take `<num>` from the PR URL (`…/pull/13` ⇒ `13`); **always write
-it when a PR was created** (the `gh` path) — it is what the dashboard turns into a PR link. If only a
-compare URL was emitted (no PR yet), move the card without a number. Then verify with a **grep for
-`#$ARGUMENTS`** on the board (with surrounding heading context — `grep -B20 '#$ARGUMENTS' | grep '^##'`
-or an offset-limited Read around the match): exactly one card, under the `shipped` heading — never
-re-read the whole board into context. No board ⇒ skip silently.
+Then **read the script's own output**, which is the verification: `moved #$ARGUMENTS -> Shipped
+(PR #<num>)` means done, and a `kanban: <reason>` line means the mirror is off and says why. Both are
+exit 0 and they are not interchangeable — say which one you got. Only if it moved, confirm placement
+with a **grep for `#$ARGUMENTS`** on the board it named (with surrounding heading context —
+`grep -B20 '#$ARGUMENTS' | grep '^##'`, or an offset-limited Read around the match): exactly one card,
+under the `shipped` heading — never re-read the whole board into context.
 
 **Telemetry — the usage ping that closes the funnel.** Chain it onto the verify call above
 (`/cohorte-build` §4's shared form, `<phase>` = `ship`, `<seconds>` = `0` — the release agent's duration is
@@ -70,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/commands/cohorte-spec.md

@@ -17,8 +17,12 @@ You run the **spec** step in the main thread — interactive, with the human. Pa
 > line per standing decision, so it is cheap. It is the ONLY place the project's transverse rules
 > live; a spec that contradicts one silently un-decides it. Absent ⇒ nothing to honour yet.
 >
-> **Kanban** (SCHEMA.md §Kanban): when the spec opens, move card `#<feature_id>` → **Spec**; on freeze
-> (`status: frozen`, Mode A) → **Ready to build**. No-op silently if no board is configured.
+> **Kanban** (SCHEMA.md §Kanban): when the spec opens, run
+> `<core>/pipeline/scripts/kanban-move.sh auto <feature_id> spec --title "<human title>"`; on freeze
+> (`status: frozen`, Mode A), the same call with `ready`. `<core>` = `.claude` bundled / `~/.claude`
+> global — probe with `test -x`. `auto` resolves the board from the config itself and exits 0 with a
+> `kanban: <reason>` line when there is none — so **never decide "no board is configured" without
+> running it**.
 
 Detect the mode from the pasted content:
 

package/core/commands/cohorte-update-pipeline.md

@@ -102,14 +102,20 @@ Four of the §Reconcile steps matter specifically here:
   (pre-telemetry install), top up the block from the template and ask the ONE opt-in consent
   question defined in `templates/steps/init-pipeline/02-interview-gaps.md` §Telemetry — record the
   answer either way so it is never re-asked. Consent is strictly opt-in; "No" is the default.
-- **Kanban sync** (§Reconcile step 6): resolve this project's board from `kanban.boards[<PIPELINE
-  name>]`. **Not linked** → offer to link/create a board (confirm the vault + `<folder>/Tasks.md`,
+- **Kanban sync** (§Reconcile step 6): resolve this project's board with
+  `<core>/pipeline/scripts/kanban-move.sh --check` — it prints either the board path or the exact
+  missing link. **Not linked** → offer to link/create a board (confirm the vault + `<folder>/Tasks.md`,
   write the `boards` entry, create the board file per §Kanban). **Linked** → verify the board file
   exists (recreate if the human confirms) and its columns match `kanban.columns` (repair drift). Either
-  way, run the §Kanban **full sync/backfill** from `specs/*.md` — this is what adds every
-  already-developed feature to the board and repositions cards to match each spec's `status`. Report
-  cards added / moved / already-correct. Skip silently if `kanban.enabled` is false and the human
-  doesn't want to turn it on.
+  way, run the §Kanban **full sync/backfill** from `specs/*.md` — one
+  `kanban-move.sh auto <id> <stage>` per spec, `<stage>` from the status mapping — this is what adds
+  every already-developed feature to the board and repositions cards to match each spec's `status`.
+  Report cards added / moved / already-correct. Skip silently if `kanban.enabled` is false and the
+  human doesn't want to turn it on.
+- **A project renamed since its last update loses its board silently** — `boards` is keyed by the
+  profile `name`, so a `name:` edit orphans the old entry and no lookup matches the new one. When
+  `--check` finds no entry for `<name>` but `boards` holds exactly one other key whose board file
+  exists, say so and offer to re-key it rather than creating a second board.
 
 ## 4. Tell the human the follow-ups
 

package/core/hooks/gate.py

@@ -4,7 +4,9 @@
 Forces a confirmation prompt (or hard-denies) on dangerous Bash commands,
 inspecting the FULL command string so chained forms like
 `cd apps/api && node ace migration:run` are caught — something prefix-based
-permission rules in settings.json miss.
+permission rules in settings.json miss. Branch-conditional patterns follow that
+same chain: a leading `cd <dir>` moves where the branch is resolved, so
+`cd <other repo> && git commit` is judged against the checkout it lands in.
 
 Patterns come from `.claude/gate-config.json` (generated by /cohorte-init-pipeline from
 the PIPELINE.md `gate` block):
@@ -91,6 +93,36 @@ def session_cwd(payload: dict) -> str:
     return payload.get("cwd") or project_root()
 
 
+CD = re.compile(r"^cd\s+(?!-\s*$)(?P<path>.+)$")
+
+
+def cd_target(seg: str, cwd: str):
+    """The directory a `cd <path>` segment lands in, or None if this segment is
+    not a plain `cd` we can resolve. Chained commands are the norm here — the
+    tool's shell has no memory between calls, so agents write
+    `cd <other repo> && git commit`. Resolving git state at the payload cwd then
+    judges that commit against the WRONG checkout: a commit on a feature branch
+    in another repo was refused as if it were on the default branch, and no
+    approval could lift it because the branch it named was never the branch the
+    command would run on.
+
+    Deliberately narrow: one unquoted-or-quoted path, no `cd -`, no `$(…)`, no
+    variables. Anything else returns None and the caller keeps the cwd it had —
+    the conservative direction, since an unresolvable branch still gates."""
+    m = CD.match(seg)
+    if not m:
+        return None
+    path = m.group("path").strip()
+    if len(path) >= 2 and path[0] == path[-1] and path[0] in "\"'":
+        path = path[1:-1]
+    elif any(c in path for c in "$`\"'*?"):
+        return None  # expansion or globbing — we cannot know where it lands
+    path = os.path.expanduser(path)
+    target = path if os.path.isabs(path) else os.path.join(cwd, path)
+    target = os.path.normpath(target)
+    return target if os.path.isdir(target) else None
+
+
 def current_branch(cwd: str):
     """The checked-out branch at `cwd`, or None (not a repo / detached / git absent)."""
     try:
@@ -296,11 +328,17 @@ def main() -> int:
 
     # Branch-conditional patterns (e.g. git/docker) are gated only on the default branch;
     # on a feature branch they run freely. Unknown branch (no repo / detached / no git) ⇒
-    # be conservative and gate. Resolve the branch once, lazily.
-    on_default = False
-    if branch_gated:
-        branch = current_branch(session_cwd(payload))
-        on_default = branch is None or branch == default
+    # be conservative and gate. The branch is resolved per segment at the cwd that
+    # segment runs in — a leading `cd <dir>` in the same chain moves it — and cached,
+    # so the common case is still one git call.
+    cwd = session_cwd(payload)
+    branch_cache = {}
+
+    def on_default_at(directory: str) -> bool:
+        if directory not in branch_cache:
+            branch = current_branch(directory)
+            branch_cache[directory] = branch is None or branch == default
+        return branch_cache[directory]
 
     for raw in SPLIT.split(command):
         seg = norm(raw)
@@ -314,13 +352,18 @@ def main() -> int:
                 return decide(ask_decision,
                               f"`{pat}` is a gated command — confirm first (PIPELINE.md gate)."
                               f"{ask_suffix}")
-        if on_default:
+        if branch_gated and on_default_at(cwd):
             for pat in branch_gated:
                 if norm(pat) in seg:
                     return decide(ask_decision,
                                   f"`{pat}` is gated on the default branch `{default}` — confirm "
                                   f"(PIPELINE.md gate). It runs freely on feature branches."
                                   f"{ask_suffix}")
+        # Apply the `cd` AFTER matching this segment: a `cd` is not itself gated,
+        # and every later segment in the chain runs in the new directory.
+        moved = cd_target(seg, cwd)
+        if moved:
+            cwd = moved
 
     return 0
 

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.1",
+  "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`
@@ -536,16 +578,42 @@ Once shipped, `/cohorte-ship` appends the **PR number** to the card — `- [ ] <
 The bare `#<num>` is what the dashboard renders as a clickable link to the GitHub PR, so `/cohorte-ship` always
 writes it when a PR was actually created.
 
-**Move a card (the core op).** Use the shipped script — it does the whole op outside the agent's
-context (find, dedupe, sub-notes carried along, settings block preserved):
-`<core>/pipeline/scripts/kanban-move.sh <board.md> <id> <column> [--pr <num>] [--title <title>]`
-where `<core>` is `~/.claude` (global install) or `.claude` (bundled) — probe with `test -x`. It
-creates the card in the target column when none exists, keeps the first and drops duplicates, and
-appends ` — PR #<num>` with `--pr`. **Fallback when the script is absent** (older core): do it by
-hand, but never read the whole board into context — it grows with every feature ever tracked:
-`grep -n` for `#<id>` and the `## ` headings to locate lines, then use offset-limited Reads +
-targeted Edits around the matches. Either way: one card per `#<id>`, whole line moved tag-preserved,
-card created in the target column if missing.
+**Move a card (the core op).** One call — the script does resolution AND the move outside the
+agent's context (find, dedupe, sub-notes carried along, settings block preserved):
+
+```
+<core>/pipeline/scripts/kanban-move.sh auto <id> <stage> [--pr <num>] [--title <title>]
+```
+
+`<core>` is `~/.claude` (global install) or `.claude` (bundled) — probe with `test -x`. It creates
+the card in the target column when none exists, keeps the first and drops duplicates, and appends
+` — PR #<num>` with `--pr`.
+
+**`auto` is not a convenience, it is the contract.** It reads `name` from `PIPELINE.md`, then
+`kanban.enabled` / `obsidian.vault_path` / `boards[name]` from `~/.claude/cohorte.config.yaml`
+(override with `COHORTE_CONFIG`, or skip the profile with `--project <name>`), and it maps the
+**stage key** (`ideas` · `brainstorm` · `spec` · `ready` · `building` · `review` · `fix` · `ship` ·
+`shipped`) to that board's heading through `boards[name].columns` → `kanban.columns` → the built-in
+default. An explicit `<board.md>` path and a literal heading both still work, for one-off and
+non-pipeline moves.
+
+**Never conclude "no board is configured" without running it.** The command that resolves nothing
+prints `kanban: <reason>` — naming the missing link (no config file, `enabled: false`, no entry for
+this project, vault unset, board file gone) — and exits **0**. A configured board that cannot be
+moved is loud instead: exit 2 on usage, exit 3 on a missing board file or an unknown column. Both
+readings are on stdout, so a caller reports which one it got. This exists because inference was the
+actual failure mode: with only "no-op silently if no board" to go on, a fresh phase session (every
+phase runs after a `/clear`) decided there was no board without ever opening the config, and cards
+stopped moving mid-pipeline while every command still reported success.
+
+**Fallback when the script is absent** (older core): do it by hand, but never read the whole board
+into context — it grows with every feature ever tracked: `grep -n` for `#<id>` and the `## ` headings
+to locate lines, then use offset-limited Reads + targeted Edits around the matches. Either way: one
+card per `#<id>`, whole line moved tag-preserved, card created in the target column if missing.
+
+**Tag before you move.** The join key is the `#<id>` tag, and an **Ideas** card a human typed by hand
+does not have one. Moving it first finds nothing, creates a second card, and strands the original in
+Ideas — so `/cohorte-brainstorm` appends the tag to the picked line before its first move.
 
 **Stage → column**, used both by each pipeline command (to move its card live) and by backfill:
 

package/scripts/kanban-move.sh

@@ -2,28 +2,219 @@
 # kanban-move.sh — move a feature card on an Obsidian Kanban board without
 # loading the board into an agent's context (SCHEMA.md §Kanban "Move a card").
 #
-#   kanban-move.sh <board.md> <feature-id> <target-column> [--pr <num>] [--title <title>]
+#   kanban-move.sh <board.md|auto> <feature-id> <column|stage> [options]
+#   kanban-move.sh --check                 resolve only: print the board this
+#                                          project maps to, or why it does not
 #
-# Behavior (mirrors the documented manual op):
+#     --pr <num>        ensure the card line ends with ` — PR #<num>`
+#     --title <title>   text to use when the card has to be created
+#     --project <name>  profile name to look up in kanban.boards (default: read
+#                       `name:` from ./PIPELINE.md)
+#     --profile <path>  where to read that name from (default: ./PIPELINE.md)
+#
+# `auto` as the board resolves the board FROM THE CONFIG — vault path, this
+# project's board file, and the stage→heading mapping — instead of making the
+# caller do it. This exists because the callers are agents: told only "no-op
+# silently if no board", a fresh session (every phase runs after a /clear)
+# concluded "no board is configured" without ever opening the config, and the
+# card silently stopped moving mid-pipeline. Resolution is not a judgment call,
+# so it is not left to one. When nothing resolves the script says which link is
+# missing on stdout and exits 0 — a no-op you can read, never one you infer.
+#
+# Behavior of the move itself (mirrors the documented manual op):
 #   - finds the list item tagged #<feature-id> (plus its indented sub-notes),
 #     removes it from its current column, appends it under `## <target-column>`
 #   - no card yet ⇒ creates `- [ ] <title|id>  #<id>` in the target column
 #   - duplicates ⇒ keeps the first, drops the rest
-#   - --pr N ⇒ ensures the card line ends with ` — PR #N`
 #   - never touches the front-matter or the trailing `%% kanban:settings %%` block
-# Exit codes: 0 ok · 2 usage · 3 board/column not found.
+#
+# Exit codes: 0 ok (incl. "kanban not configured") · 2 usage · 3 board/column
+# not found. A configured board that cannot be moved is loud; an unconfigured
+# one is quiet — the pipeline never blocks on the board.
 set -eu
 
-[ $# -ge 3 ] || { echo "usage: kanban-move.sh <board.md> <feature-id> <column> [--pr <num>] [--title <title>]" >&2; exit 2; }
-board="$1"; id="$2"; col="$3"; shift 3
-pr=""; title=""
+usage='usage: kanban-move.sh <board.md|auto> <feature-id> <column|stage> [--pr <num>] [--title <title>] [--project <name>] [--profile <path>]
+       kanban-move.sh --check [--project <name>] [--profile <path>]'
+check_only=false
+if [ "${1-}" = --check ]; then
+  check_only=true; board=auto; id=""; col=""; shift
+else
+  [ $# -ge 3 ] || { echo "$usage" >&2; exit 2; }
+  board="$1"; id="$2"; col="$3"; shift 3
+fi
+pr=""; title=""; project=""; profile="PIPELINE.md"
 while [ $# -gt 0 ]; do
   case "$1" in
-    --pr)    pr="$2"; shift 2 ;;
-    --title) title="$2"; shift 2 ;;
-    *) echo "error: unknown flag $1" >&2; exit 2 ;;
+    --pr)      pr="${2-}";      shift 2 ;;
+    --title)   title="${2-}";   shift 2 ;;
+    --project) project="${2-}"; shift 2 ;;
+    --profile) profile="${2-}"; shift 2 ;;
+    *) echo "error: unknown flag $1" >&2; echo "$usage" >&2; exit 2 ;;
   esac
 done
+
+TAB=$(printf '\t')
+CONFIG="${COHORTE_CONFIG:-$HOME/.claude/cohorte.config.yaml}"
+
+# The nine pipeline stages and their default headings. A stage key given as the
+# target column is mapped through the config (per-board `columns` first, then the
+# global `kanban.columns`) and falls back to these — so a stage key works even
+# with an explicit board path and no config at all. Anything not in this list is
+# taken as a literal heading, which keeps hand-written columns working.
+default_heading() {
+  case "$1" in
+    ideas)      echo "Ideas" ;;
+    brainstorm) echo "Brainstorm" ;;
+    spec)       echo "Spec" ;;
+    ready)      echo "Ready to build" ;;
+    building)   echo "Building" ;;
+    review)     echo "Review" ;;
+    fix)        echo "Fix" ;;
+    ship)       echo "Ship" ;;
+    shipped)    echo "Shipped" ;;
+    *)          echo "" ;;
+  esac
+}
+
+# Read `name:` from the profile's `yaml pipeline-profile` block. Only the block —
+# a `name:` under some other key (a surface, a persona) is not the project name.
+read_project_name() {
+  [ -f "$1" ] || return 0
+  awk '
+    /^```[ \t]*yaml[ \t]+pipeline-profile/ { inblock = 1; next }
+    /^```/                                 { if (inblock) exit }
+    inblock && /^name:[ \t]/ {
+      v = $0; sub(/^name:[ \t]*/, "", v)
+      sub(/[ \t]+#.*$/, "", v); sub(/[ \t]+$/, "", v)
+      gsub(/^["\047]|["\047]$/, "", v)
+      print v; exit
+    }
+  ' "$1"
+}
+
+# Minimal YAML reader for the fixed shape the installer writes. Not a general
+# parser: it walks an indent stack and emits only the handful of paths the kanban
+# mirror needs, resolved against the project name we were given (so a name with a
+# dot in it still matches — the comparison is on whole strings, not a joined key).
+read_config() {
+  PROJ="$1" awk '
+    function clean(v,   c, q, i, ch, out) {
+      sub(/^[ \t]+/, "", v)
+      if (v == "") return ""
+      c = substr(v, 1, 1)
+      if (c == "\"" || c == "\047") {
+        q = c; out = ""
+        for (i = 2; i <= length(v); i++) {
+          ch = substr(v, i, 1)
+          if (ch == q) break
+          out = out ch
+        }
+        return out
+      }
+      sub(/[ \t]+#.*$/, "", v); sub(/[ \t]+$/, "", v)
+      return v
+    }
+    # `columns: { ideas: "Idées", ready: "Prêt" }` — the flow form the config
+    # template documents for a per-board override.
+    function flow(path, v,   n, i, parts, p, k) {
+      sub(/^\{[ \t]*/, "", v); sub(/[ \t]*\}[ \t]*$/, "", v)
+      n = split(v, parts, ",")
+      for (i = 1; i <= n; i++) {
+        p = index(parts[i], ":")
+        if (p == 0) continue
+        k = substr(parts[i], 1, p - 1)
+        gsub(/^[ \t]+|[ \t]+$/, "", k)
+        emit(path "." k, clean(substr(parts[i], p + 1)))
+      }
+    }
+    function emit(path, v,   stage) {
+      if (v == "") return
+      if (path == "enabled")             { print "ENABLED\t" v; return }
+      if (path == "kanban.enabled")      { print "KENABLED\t" v; return }
+      if (path == "obsidian.vault_path") { print "VAULT\t" v; return }
+      if (path == "kanban.boards." proj ".board") { print "BOARD\t" v; return }
+      if (index(path, "kanban.columns.") == 1) {
+        print "COL." substr(path, length("kanban.columns.") + 1) "\t" v; return
+      }
+      if (index(path, "kanban.boards." proj ".columns.") == 1) {
+        print "BCOL." substr(path, length("kanban.boards." proj ".columns.") + 1) "\t" v; return
+      }
+    }
+    BEGIN { proj = ENVIRON["PROJ"]; top = 0 }
+    {
+      line = $0; sub(/\r$/, "", line)
+      if (line ~ /^[ \t]*$/ || line ~ /^[ \t]*#/) next
+      match(line, /^[ ]*/); ind = RLENGTH
+      rest = substr(line, ind + 1)
+      if (rest ~ /^- /) next
+      p = index(rest, ":")
+      if (p == 0) next
+      key = substr(rest, 1, p - 1)
+      if (key ~ /[ \t]/) next
+      raw = substr(rest, p + 1)
+      while (top > 0 && indent[top] >= ind) top--
+      top++; indent[top] = ind; keyat[top] = key
+      path = ""
+      for (i = 1; i <= top; i++) path = path (i > 1 ? "." : "") keyat[i]
+      sub(/^[ \t]+/, "", raw)
+      if (substr(raw, 1, 1) == "{") { flow(path, raw); next }
+      emit(path, clean(raw))
+    }
+  ' "$CONFIG"
+}
+
+off() { echo "kanban: $1"; exit 0; }
+
+cfg=""
+if [ "$board" = auto ] || [ -n "$(default_heading "$col")" ]; then
+  [ -n "$project" ] || project=$(read_project_name "$profile")
+  [ -f "$CONFIG" ] && cfg=$(read_config "$project") || cfg=""
+fi
+
+# ── resolve the board ───────────────────────────────────────────────────────
+if [ "$board" = auto ]; then
+  [ -f "$CONFIG" ] || off "no config at $CONFIG — board mirror off"
+  vault=""; rel=""; enabled=""; kenabled=""
+  OLDIFS=$IFS; IFS=$TAB
+  while read -r k v; do
+    case "$k" in
+      ENABLED)  enabled=$v ;;
+      KENABLED) kenabled=$v ;;
+      VAULT)    vault=$v ;;
+      BOARD)    rel=$v ;;
+    esac
+  done <<EOF
+$cfg
+EOF
+  IFS=$OLDIFS
+  [ "$enabled" != false ]  || off "cohorte capabilities disabled (enabled: false in $CONFIG)"
+  [ "$kenabled" != false ] || off "disabled in $CONFIG (kanban.enabled: false)"
+  [ -n "$project" ]        || off "no project name in $profile — cannot resolve a board"
+  [ -n "$rel" ]            || off "no board configured for project \"$project\" in $CONFIG"
+  [ -n "$vault" ]          || off "obsidian.vault_path not set in $CONFIG"
+  board="$vault/$rel"
+  [ -f "$board" ] || off "board file not found: $board"
+  if $check_only; then echo "kanban: project \"$project\" -> $board"; exit 0; fi
+fi
+
+# ── resolve the column ──────────────────────────────────────────────────────
+# A stage key becomes a heading; a literal heading passes through untouched.
+if [ -n "$(default_heading "$col")" ]; then
+  heading=""
+  OLDIFS=$IFS; IFS=$TAB
+  while read -r k v; do
+    case "$k" in
+      "BCOL.$col") heading=$v ;;
+      "COL.$col")  [ -n "$heading" ] || heading=$v ;;
+    esac
+  done <<EOF
+$cfg
+EOF
+  IFS=$OLDIFS
+  [ -n "$heading" ] || heading=$(default_heading "$col")
+  col="$heading"
+fi
+
 [ -f "$board" ] || { echo "error: board not found: $board" >&2; exit 3; }
 
 tmp="${board}.kanban-move.$$"

package/scripts/test-gate.mjs

@@ -155,6 +155,36 @@ console.log("gate.py — branch-conditional gating");
   const norepo = scratch(); writeConfig(norepo, GATE_CFG);
   check("unknown branch (not a repo) ⇒ gated, to stay safe",
     run({ ...bash("git commit -m x"), cwd: norepo }, { projectDir: norepo }).decision === "ask");
+
+  // 2.0.2: the tool's shell keeps no cwd between calls, so agents write
+  // `cd <other repo> && git commit`. Resolving the branch at the payload cwd
+  // judged that commit against the wrong checkout — and the refusal named a
+  // branch the command was never going to run on, so no approval could lift it.
+  const chained = run({ ...bash(`cd ${feat} && git commit -m x`), cwd: main }, { projectDir: main });
+  check("`cd <feature checkout> && git commit` follows the cd ⇒ free",
+    chained.decision === null, `got ${chained.decision}: ${chained.reason}`);
+  check("`cd <default-branch checkout> && git commit` still gated",
+    run({ ...bash(`cd ${main} && git commit -m x`), cwd: feat }, { projectDir: feat }).decision === "ask");
+  check("a cd only affects segments AFTER it",
+    run({ ...bash(`git commit -m x && cd ${feat}`), cwd: main }, { projectDir: main }).decision === "ask");
+  check("relative cd resolves against the payload cwd",
+    run({ ...bash("cd .. && git commit -m x"), cwd: join(feat, ".claude") },
+        { projectDir: feat }).decision === null);
+  check("cd into a missing dir keeps the current cwd (still gated)",
+    run({ ...bash("cd /definitely/not/here && git commit -m x"), cwd: main },
+        { projectDir: main }).decision === "ask");
+  check("an unresolvable cd ($(…)) keeps the current cwd (still gated)",
+    run({ ...bash("cd $(mktemp -d) && git commit -m x"), cwd: main },
+        { projectDir: main }).decision === "ask");
+  check("`cd -` is never treated as a resolvable move",
+    run({ ...bash("cd - && git commit -m x"), cwd: main }, { projectDir: main }).decision === "ask");
+  check("a quoted cd path with a space is followed",
+    run({ ...bash(`cd "${feat}" && git commit -m x`), cwd: main }, { projectDir: main }).decision === null);
+  // A cd must not soften the unconditional tiers — those are branch-independent.
+  check("cd does not exempt a `deny` pattern",
+    run({ ...bash(`cd ${feat} && node ace db:wipe`), cwd: main }, { projectDir: main }).decision === "deny");
+  check("cd does not exempt an always-`ask` pattern",
+    run({ ...bash(`cd ${feat} && psql`), cwd: main }, { projectDir: main }).decision === "ask");
 }
 
 // ── config robustness ────────────────────────────────────────────────────────

package/scripts/test-kanban.mjs

@@ -0,0 +1,304 @@
+#!/usr/bin/env node
+// Behavioural tests for scripts/kanban-move.sh — the board mirror's only writer.
+//
+// The mirror's failure mode is not a crash, it is silence: every call site chains
+// `|| true`, so a card that stops moving looks exactly like a project with no
+// board. That is how a shipped feature sat in "Ready to build" for a day — the
+// ship session decided, without opening the config, that no board was configured.
+// `auto` moved that decision out of the agent and into here, so here is where it
+// has to be pinned: what resolves, what refuses to resolve, and the fact that a
+// refusal SAYS WHY on stdout instead of exiting quietly.
+//
+//   node scripts/test-kanban.mjs
+
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = fileURLToPath(new URL("..", import.meta.url));
+const SCRIPT = join(root, "scripts", "kanban-move.sh");
+
+let failures = 0;
+const check = (name, cond, detail = "") => {
+  if (cond) console.log(`  ✓ ${name}`);
+  else { failures++; console.error(`  ✗ ${name}${detail ? ` — ${detail}` : ""}`); }
+};
+
+const tmps = [];
+function scratch() {
+  const d = mkdtempSync(join(tmpdir(), "kanban-"));
+  tmps.push(d);
+  return d;
+}
+
+const COLUMNS = ["Ideas", "Brainstorm", "Spec", "Ready to build", "Building",
+                 "Review", "Fix", "Ship", "Shipped"];
+
+function board(dir, cards = {}, name = "Tasks.md") {
+  const body = [
+    "---", "", "kanban-plugin: board", "", "---", "",
+    ...COLUMNS.flatMap((c) => ["## " + c, "", ...(cards[c] || []), ""]),
+    "%% kanban:settings", "```",
+    JSON.stringify({ "kanban-plugin": "board", "list-collapse": COLUMNS.map(() => false) }),
+    "```", "%%", "",
+  ].join("\n");
+  const p = join(dir, name);
+  writeFileSync(p, body);
+  return p;
+}
+
+function config(dir, { project = "demo", vault, boardRel = "Demo/Tasks.md",
+                       enabled = true, kanbanEnabled = true, columns, boardColumns } = {}) {
+  const lines = [
+    `enabled: ${enabled}                 # cfg:enabled`,
+    "",
+    "obsidian:",
+    `  vault_path: "${vault}"  # cfg:vault_path`,
+    "",
+    "kanban:",
+    `  enabled: ${kanbanEnabled}               # cfg:kanban_enabled`,
+    "  columns:",
+    ...Object.entries(columns || {
+      ideas: "Ideas", brainstorm: "Brainstorm", spec: "Spec", ready: "Ready to build",
+      building: "Building", review: "Review", fix: "Fix", ship: "Ship", shipped: "Shipped",
+    }).map(([k, v]) => `    ${k}: "${v}"`),
+    "  boards:",
+    `    ${project}:`,
+    `      board: "${boardRel}"`,
+    ...(boardColumns ? [`      columns: { ${boardColumns} }`] : []),
+  ];
+  const p = join(dir, "cohorte.config.yaml");
+  writeFileSync(p, lines.join("\n") + "\n");
+  return p;
+}
+
+function profile(dir, name) {
+  writeFileSync(join(dir, "PIPELINE.md"), [
+    "# PIPELINE.md", "",
+    "```yaml pipeline-profile",
+    "# ── identity ──",
+    `name: ${name}`,
+    "ui_language: French",
+    "surfaces:",
+    "  - key: backend",
+    "    name: not-the-project-name",
+    "```", "",
+  ].join("\n"));
+}
+
+function run(args, { cwd, config: cfg } = {}) {
+  const r = spawnSync("sh", [SCRIPT, ...args], {
+    cwd, encoding: "utf8",
+    env: { ...process.env, ...(cfg ? { COHORTE_CONFIG: cfg } : {}) },
+  });
+  return { status: r.status, out: (r.stdout || "").trim(), err: (r.stderr || "").trim() };
+}
+
+const columnOf = (path, id) => {
+  let col = null;
+  for (const line of readFileSync(path, "utf8").split("\n")) {
+    if (line.startsWith("## ")) col = line.slice(3).trim();
+    else if (line.includes("#" + id)) return col;
+  }
+  return null;
+};
+
+// ── explicit board path (the pre-existing contract) ─────────────────────────
+console.log("explicit board");
+{
+  const d = scratch();
+  const b = board(d, { "Ready to build": ["- [ ] Some feature  #feat-a"] });
+  const r = run([b, "feat-a", "Shipped", "--pr", "42"]);
+  check("moves a card to a literal heading", r.status === 0 && columnOf(b, "feat-a") === "Shipped", r.err);
+  check("appends the PR number", readFileSync(b, "utf8").includes("#feat-a — PR #42"));
+}
+{
+  const d = scratch();
+  const b = board(d);
+  const r = run([b, "feat-new", "Spec", "--title", "Brand new"]);
+  check("creates a missing card", r.status === 0 && columnOf(b, "feat-new") === "Spec", r.err);
+  check("uses --title for the new card", readFileSync(b, "utf8").includes("- [ ] Brand new  #feat-new"));
+}
+{
+  const d = scratch();
+  const b = board(d, { Ideas: ["- [ ] Dup  #dup", "- [ ] Dup again  #dup"] });
+  run([b, "dup", "Building"]);
+  const hits = readFileSync(b, "utf8").split("\n").filter((l) => l.includes("#dup")).length;
+  check("collapses duplicates to one card", hits === 1, `found ${hits}`);
+}
+{
+  const d = scratch();
+  const b = board(d, { Ideas: ["- [ ] Parent  #par", "  - a sub-note", "  - another"] });
+  run([b, "par", "Brainstorm"]);
+  const txt = readFileSync(b, "utf8");
+  check("carries sub-notes along", columnOf(b, "par") === "Brainstorm" && txt.includes("  - a sub-note"));
+  check("leaves the settings block intact", txt.includes("%% kanban:settings"));
+}
+{
+  const d = scratch();
+  const b = board(d, { Ideas: ["- [ ] X  #x"] });
+  const r = run([b, "x", "Nonexistent column"]);
+  check("unknown literal column is a loud failure (exit 3)", r.status === 3, `exit ${r.status}`);
+  const r2 = run(["/nope/board.md", "x", "Ideas"]);
+  check("missing explicit board is a loud failure (exit 3)", r2.status === 3, `exit ${r2.status}`);
+}
+{
+  const d = scratch();
+  const b = board(d, { Ideas: ["- [ ] X  #x"] });
+  for (let i = 0; i < 6; i++) run([b, "x", i % 2 ? "Ideas" : "Building"]);
+  const blanks = (readFileSync(b, "utf8").match(/\n\n\n/g) || []).length;
+  check("repeated moves do not pad the board with blank lines", blanks === 0,
+        `${blanks} runs of blank lines after 6 moves`);
+}
+
+// ── auto resolution (the fix) ───────────────────────────────────────────────
+console.log("auto resolution");
+{
+  const d = scratch();
+  const vault = join(d, "vault");
+  mkdirSync(join(vault, "Demo"), { recursive: true });
+  const b = board(join(vault, "Demo"), { "Ready to build": ["- [ ] Feature  #feat-b"] });
+  const cfg = config(d, { project: "demo", vault });
+  const repo = scratch();
+  profile(repo, "demo");
+  const r = run(["auto", "feat-b", "shipped", "--pr", "7"], { cwd: repo, config: cfg });
+  check("resolves vault + board + stage from the config",
+        r.status === 0 && columnOf(b, "feat-b") === "Shipped", `${r.err} ${r.out}`);
+  check("reports the move", r.out.startsWith("moved #feat-b"), r.out);
+}
+{
+  const d = scratch();
+  const vault = join(d, "vault");
+  mkdirSync(join(vault, "Demo"), { recursive: true });
+  const b = board(join(vault, "Demo"));
+  const cfg = config(d, { project: "demo", vault });
+  const repo = scratch();
+  profile(repo, "demo");
+  const stages = { ideas: "Ideas", brainstorm: "Brainstorm", spec: "Spec", ready: "Ready to build",
+                   building: "Building", review: "Review", fix: "Fix", ship: "Ship", shipped: "Shipped" };
+  let ok = true, bad = "";
+  for (const [stage, heading] of Object.entries(stages)) {
+    run(["auto", "st", stage], { cwd: repo, config: cfg });
+    if (columnOf(b, "st") !== heading) { ok = false; bad = `${stage} → ${columnOf(b, "st")}`; }
+  }
+  check("every one of the nine stage keys maps to its heading", ok, bad);
+}
+{
+  const d = scratch();
+  const vault = join(d, "vault");
+  mkdirSync(join(vault, "Demo"), { recursive: true });
+  const b = board(join(vault, "Demo"), { Ideas: [], Prêt: [] }, "Tasks.md");
+  // a board whose headings are localised, declared per-board in the config
+  writeFileSync(b, readFileSync(b, "utf8").replace("## Ready to build", "## Prêt"));
+  const cfg = config(d, { project: "demo", vault, boardColumns: 'ready: "Prêt"' });
+  const repo = scratch();
+  profile(repo, "demo");
+  const r = run(["auto", "loc", "ready", "--title", "Localisé"], { cwd: repo, config: cfg });
+  check("per-board column override beats the global mapping",
+        r.status === 0 && columnOf(b, "loc") === "Prêt", `${r.err} ${r.out}`);
+}
+{
+  const repo = scratch();
+  profile(repo, "demo");
+  const r = run(["auto", "x", "shipped"], { cwd: repo, config: join(repo, "nope.yaml") });
+  check("no config ⇒ exit 0", r.status === 0, `exit ${r.status}`);
+  check("no config ⇒ says why on stdout", /^kanban: no config at /.test(r.out), r.out);
+}
+{
+  const d = scratch();
+  const cfg = config(d, { project: "other", vault: d });
+  const repo = scratch();
+  profile(repo, "demo");
+  const r = run(["auto", "x", "shipped"], { cwd: repo, config: cfg });
+  check("project not in boards ⇒ exit 0", r.status === 0, `exit ${r.status}`);
+  check("project not in boards ⇒ names the project it looked for",
+        r.out.includes('no board configured for project "demo"'), r.out);
+}
+{
+  const d = scratch();
+  const cfg = config(d, { project: "demo", vault: d, kanbanEnabled: false });
+  const repo = scratch();
+  profile(repo, "demo");
+  const r = run(["auto", "x", "shipped"], { cwd: repo, config: cfg });
+  check("kanban.enabled: false ⇒ exit 0 with a reason",
+        r.status === 0 && r.out.includes("kanban.enabled: false"), `${r.status} ${r.out}`);
+}
+{
+  const d = scratch();
+  const cfg = config(d, { project: "demo", vault: d, enabled: false });
+  const repo = scratch();
+  profile(repo, "demo");
+  const r = run(["auto", "x", "shipped"], { cwd: repo, config: cfg });
+  check("master enabled: false ⇒ exit 0 with a reason",
+        r.status === 0 && r.out.includes("enabled: false"), `${r.status} ${r.out}`);
+}
+{
+  const d = scratch();
+  const cfg = config(d, { project: "demo", vault: join(d, "vault"), boardRel: "Demo/Gone.md" });
+  const repo = scratch();
+  profile(repo, "demo");
+  const r = run(["auto", "x", "shipped"], { cwd: repo, config: cfg });
+  check("configured board file missing ⇒ exit 0, names the path",
+        r.status === 0 && r.out.includes("board file not found"), `${r.status} ${r.out}`);
+}
+{
+  const repo = scratch(); // no PIPELINE.md at all
+  const d = scratch();
+  const cfg = config(d, { project: "demo", vault: d });
+  const r = run(["auto", "x", "shipped"], { cwd: repo, config: cfg });
+  check("no profile ⇒ exit 0 with a reason",
+        r.status === 0 && r.out.includes("no project name"), `${r.status} ${r.out}`);
+}
+{
+  // The profile's `name:` is the one in the pipeline-profile block — not a
+  // `name:` nested under a surface, which is what a naive grep would find.
+  const d = scratch();
+  const vault = join(d, "vault");
+  mkdirSync(join(vault, "Demo"), { recursive: true });
+  const b = board(join(vault, "Demo"));
+  const cfg = config(d, { project: "demo", vault });
+  const repo = scratch();
+  profile(repo, "demo");
+  const r = run(["auto", "nested", "spec"], { cwd: repo, config: cfg });
+  check("reads the profile name from the pipeline-profile block only",
+        r.status === 0 && columnOf(b, "nested") === "Spec", `${r.err} ${r.out}`);
+}
+{
+  const d = scratch();
+  const vault = join(d, "vault");
+  mkdirSync(join(vault, "Demo"), { recursive: true });
+  const b = board(join(vault, "Demo"));
+  const cfg = config(d, { project: "demo", vault });
+  const r = run(["auto", "ov", "ship", "--project", "demo"], { cwd: scratch(), config: cfg });
+  check("--project overrides profile lookup",
+        r.status === 0 && columnOf(b, "ov") === "Ship", `${r.err} ${r.out}`);
+}
+{
+  const d = scratch();
+  const vault = join(d, "vault");
+  mkdirSync(join(vault, "Demo"), { recursive: true });
+  const b = board(join(vault, "Demo"));
+  const cfg = config(d, { project: "demo", vault });
+  const repo = scratch();
+  profile(repo, "demo");
+  const before = readFileSync(b, "utf8");
+  const r = run(["--check"], { cwd: repo, config: cfg });
+  check("--check names the resolved board",
+        r.status === 0 && r.out === `kanban: project "demo" -> ${b}`, r.out);
+  check("--check does not touch the board", readFileSync(b, "utf8") === before);
+  const r2 = run(["--check"], { cwd: scratch(), config: cfg });
+  check("--check reports the reason when nothing resolves",
+        r2.status === 0 && r2.out.startsWith("kanban: no project name"), r2.out);
+}
+{
+  const r = run(["auto", "x"]);
+  check("too few arguments is a usage error (exit 2)", r.status === 2, `exit ${r.status}`);
+  const r2 = run(["auto", "x", "shipped", "--bogus", "1"]);
+  check("unknown flag is a usage error (exit 2)", r2.status === 2, `exit ${r2.status}`);
+}
+
+for (const d of tmps) rmSync(d, { recursive: true, force: true });
+if (failures) { console.error(`\n${failures} failing check(s)`); process.exit(1); }
+console.log("\nall kanban checks passed");

package/scripts/validate-core.mjs

@@ -150,6 +150,27 @@ for (const f of readdirSync(join(root, "core/commands"))) {
     fail(`core/commands/${f}`, "non-funnel command pings telemetry — outside the consented scope");
 }
 
+// ── kanban call sites ───────────────────────────────────────────────────────
+// Every pipeline stage moves a card, and a stage that only *describes* the move
+// ("move card #<id> → Building, no-op silently if no board") leaves the agent to
+// decide whether a board exists — which it does by not looking. That is not
+// hypothetical: a /cohorte-ship session declared "no kanban board configured",
+// having opened neither the config nor PIPELINE.md, and a merged feature's card
+// stayed in "Ready to build". `kanban-move.sh auto` moved resolution into the
+// script; this keeps it there. Prose is not a call site — the literal invocation is.
+const KANBAN_STAGES = ["brainstorm", "spec", "build", "review", "fix", "ship"];
+for (const c of KANBAN_STAGES) {
+  const path = `core/commands/${PREFIX}${c}.md`;
+  const text = read(path);
+  if (!/kanban-move\.sh\s+auto\s+\S/.test(text))
+    fail(path, "moves a kanban card without a literal `kanban-move.sh auto …` call — the agent is left to infer whether a board exists");
+  // The one sentence that turns an unread config into a reported no-op. Match on
+  // unwrapped text: these live in `>` blockquotes and wrap mid-sentence.
+  const flat = text.replace(/\n>?\s*/g, " ");
+  if (!/without\s+running\s+it/i.test(flat))
+    fail(path, "no instruction to run the resolver before concluding there is no board");
+}
+
 // ── shipped scripts ─────────────────────────────────────────────────────────
 // Every scripts/*.sh must be copied by BOTH shell installers. Callers chain these
 // with `|| true`, so one an installer forgets is a silent no-op forever — no kanban