cohorte 2.8.0 → 2.10.0

package/core/commands/cohorte-retro.md

@@ -0,0 +1,85 @@
+---
+description: Mine the accumulated review findings across features for repeating patterns, and turn the ones the human ratifies into PIPELINE.md §Conventions rules the next build already follows.
+argument-hint: [last <n> | all]  (default: every feature with a report on disk)
+---
+
+You are running the **retrospective**. Every review this pipeline has run left structured
+residue on disk — verdicts, Remediation rounds, deferred backlog items. A finding that shows up
+once is a bug; the same finding shape across features is a **missing rule**, and the pipeline
+has a place for rules the implementers actually read: `PIPELINE.md` §Conventions, baked into
+each surface agent at render time. This command closes that loop: findings → patterns →
+ratified rules → re-rendered agents. The next build then never produces the finding again —
+which is cheaper than any number of review rounds catching it.
+
+> Read `PIPELINE.md` §`pipeline-profile` (`surfaces`, and skim the existing §Conventions
+> stanzas — a rule that already exists is a finding about *enforcement*, not a missing rule)
+> and `specs/_decisions.md` §Live. _Skip the re-read if already in context and unmodified._
+
+## 1. Collect — mechanical, redirected, no judgment yet
+
+Scope: `all` (default), or `last <n>` features by spec mtime. In as few Bash calls as possible,
+**always redirected to `specs/reports/retro-scan.txt` and grepped — never into your context**:
+
+- `specs/reports/*.verdict.json` — per feature: `blocking_items` (normalized identities),
+  `severity`, per-surface counts. The freshest machine record, one per feature.
+- Every non-`_` spec's `## Remediation` section — the **persistent** history (verdict.json is
+  overwritten per round; Remediation accumulates, and collapsed rounds still carry their
+  count line). Grep the item lines: `- [x?] <SEVERITY> · <file:line> · <kind> · <fix>`.
+- `specs/refactor-backlog.md` — the `deferred:<id>` tagged items: debt reviews kept finding
+  but no feature owned.
+
+A repo with fewer than two features' worth of residue ⇒ say the retro has nothing statistical
+to stand on yet, name what exists, and stop — one feature's findings are that feature's story,
+not a pattern.
+
+## 2. Patterns — what repeats, with the evidence attached
+
+A **pattern** is a finding shape that recurs where recurrence means something:
+
+- same `kind` × same surface across **≥ 2 features** (e.g. `security` findings on `backend`
+  twice running — the strongest signal there is);
+- the same file/module named by findings from **≥ 2 features** (a hotspot no single fix loop
+  owns);
+- the same *fix wording* family recurring (e.g. three "add the authz check" fixes = one
+  missing authorization convention);
+- a `deferred:` cluster in one domain — debt the reviews keep re-discovering because no rule
+  makes the implementers avoid adding to it.
+
+For each pattern, produce: the evidence lines **verbatim** (`<feature> · <severity> · <file> ·
+<problem/fix>`), the count, and ONE drafted convention rule — **rule-shaped**: a sentence an
+implementer can follow and a reviewer can test a diff against, placed under `### Shared` or the
+owning `### Surface: <key>`. Not advice ("be careful with auth") — a rule ("every route under
+`apps/api/src/routes/` calls `authorize()` before its handler; no exceptions without a spec
+§5 note"). Skip any pattern the existing §Conventions already covers — report those separately
+as **enforcement gaps** (the rule exists and reviews keep finding violations: that is input for
+the human, not a new rule).
+
+## 3. Ratify — the human picks; nothing lands without them
+
+Present a compact table: pattern → evidence count → drafted rule → target stanza. Then **stop
+and ask** which to adopt (all / some / none — none is a fine outcome and says the rulebook fits
+the codebase). Rules are standing law every future dispatch pays tokens to carry: the human
+decides what becomes law, exactly as they freeze specs.
+
+## 4. Apply — and keep the baked slices honest
+
+For each adopted rule, in this order:
+
+1. Append it to `PIPELINE.md` §Conventions under its stanza (create the `### Surface: <key>`
+   stanza if absent; keep it rule-shaped, one line each).
+2. **Re-render every affected surface agent** per SCHEMA.md §Rendering step 2 — the
+   `<SURFACE_CONVENTIONS>` slice is **baked at render time**, so a §Conventions edit without a
+   re-render produces the worst outcome available: reviewers (who read the prose live) enforce
+   a rule implementers (who carry the stale bake) have never seen, and every future review
+   round re-finds the pattern this retro just paid to close. If you cannot re-render on this
+   runtime, say so and route to `/cohorte-update-pipeline` (its reconcile step 2 re-renders) —
+   but then the rule is **pending**, and you say that too.
+3. Append ONE line per adopted rule to `specs/_decisions.md` §Live (SCHEMA.md §Decisions):
+   `- <date> · conventions · <rule, compressed> — because <kind>×<n> across <features> · retro`.
+   A retro rule is a standing decision; the journal is where the next `/cohorte-spec` learns it
+   without re-mining the reports.
+
+In chat print ONLY: patterns found / adopted / skipped (one line each), enforcement gaps, which
+agents were re-rendered (or the pending route), and the decisions lines appended. The evidence
+stays in `specs/reports/retro-scan.txt`. **Recommend a `/clear`** — everything that matters is
+now in `PIPELINE.md`, the rendered agents, and the journal.

package/core/commands/cohorte-review.md

@@ -12,7 +12,8 @@ You are the **lead**. Dispatch the review for feature **$ARGUMENTS**.
 > **Kanban** (SCHEMA.md §Kanban): run
 > `<core>/pipeline/scripts/kanban-move.sh auto $ARGUMENTS review`. `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**.
+> configured" without running it**. _(PR mode — `--pr` below — skips this entirely: an incoming
+> PR is not a pipeline feature and has no card.)_
 >
 <!-- cohorte:if workflows -->
 > **Workflow variant** (opt-in — SCHEMA.md §Workflows): on Claude Code ≥ 2.1.154 with workflows
@@ -20,6 +21,57 @@ You are the **lead**. Dispatch the review for feature **$ARGUMENTS**.
 > This conversational path stays the default and the fallback; `/cohorte-doctor` shows which is available.
 <!-- cohorte:endif -->
 
+## PR mode — review an INCOMING pull request (`--pr <num>` or a PR URL)
+
+If `$ARGUMENTS` contains `--pr <num>` (or a GitHub PR URL — extract the number), this is not a
+pipeline feature: it is **someone else's work arriving**, reviewed with the same reviewers and the
+same report format, without pretending it went through the pipeline. What that changes, explicitly:
+**no spec** (nothing to check conformance against — reviewers run in audit mode: conventions +
+correctness + security + TDD coverage only), **no kanban move**, **no verdict.json**, **no DoD
+tick, no freshness stamp, no metrics line** — those certify pipeline features, and this is not one.
+Requires `vcs.host: github` + `gh`; otherwise say so and stop.
+
+1. **Fetch into a throwaway worktree — never touch the current checkout.** One Bash call:
+   `gh pr view <num> --json title,baseRefName,headRefName,author` (relay the one-line summary), then
+   `git fetch -f origin pull/<num>/head:cohorte-pr-<num> <baseRefName> && git worktree add ../<repo>-pr-<num> cohorte-pr-<num>`
+   — `-f` so a branch left behind by a crashed earlier run updates instead of failing, and the
+   **base ref is fetched too**: the diff below is against `origin/<baseRefName>`, and a stale
+   local base blames the PR for every commit it merely hasn't rebased onto yet.
+   The human's tree, branch and stamps stay untouched; every later step runs `-C` that worktree.
+2. **Mechanical checks inside the worktree — the commands directly, NEVER `preflight.sh`.** The
+   script's whole point is stamping `<state>/preflight.ok` in the MAIN checkout (it resolves
+   through `git-common-dir` on purpose), so running it here would overwrite the human's stamp
+   with the PR tree's digest — greening pipeline review dispatches of a tree nobody preflighted,
+   then blocking them once the worktree is gone. Instead: install dependencies first
+   (`commands.install` — a bare `worktree add` has no `node_modules`), then run the profile's
+   typecheck/lint-quiet/test-quiet yourself, each appended to the worktree's
+   `specs/reports/pr-<num>.preflight.txt`, stopping at the first failure. **Red does NOT get
+   reviewers** — same economics as §0 (a reviewer on code that doesn't compile rediscovers what
+   `tsc` printed for free) — but unlike §0 it is not an abort: the mechanical failures ARE the
+   review (severity CRITICAL, kind `quality`, the failing command + last lines) — jump to
+   step 4. An *environmental* failure (install itself failed, a missing service) is reported as
+   "not verifiable here", never as a finding against the PR.
+3. **Stage + dispatch — §1's staging procedure and §2's dispatch, minus everything spec-shaped**
+   (there is no `specs/<id>.md` to confirm and no small-diff fast path — an unknown author's
+   diff always gets a full reviewer), with three substitutions: the diff is
+   `git diff origin/<baseRefName>...HEAD` (**three-dot** — only the PR's own commits, not the
+   base's drift), staged diffs and file paths are **absolute paths into the worktree**
+   (reviewers are stateless — they must not read the main checkout), and the dispatch template's
+   spec/contract slots read
+   `spec: none (incoming PR — audit mode: PIPELINE.md conventions + quality/security/TDD only,
+   skip spec conformance)` · `contract: none`. Roll call + merge per §3 (retry once, `unreviewed`
+   forbids a clean verdict), same capped REVIEW REPORT.
+4. **Stage the report to the MAIN checkout's `specs/reports/pr-<num>.md`** (it must outlive the
+   worktree), print the verdict + severity table + CRITICAL/security digests in chat. Then —
+   **always ask the human first, posting is outward-facing** — offer:
+   `gh pr comment <num> --body-file specs/reports/pr-<num>.md` (prefix the body with one line:
+   `Automated review — cohorte pipeline (advisory)`). Never post without the explicit go-ahead;
+   "no" leaves the report on disk and that is a complete outcome.
+5. **Teardown, always** (also after a red preflight or a dead reviewer):
+   `git worktree remove --force ../<repo>-pr-<num> && git branch -D cohorte-pr-<num>`.
+
+Everything below this line is the normal pipeline-feature flow.
+
 ## 0. Deterministic pre-flight — no agents while red
 
 Run the profile's mechanical gates in ONE Bash call via the shipped script

package/core/commands/cohorte-ship.md

@@ -98,8 +98,8 @@ 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`.
+(`…/pull/13` ⇒ `13`); **always pass it when a PR was created** (the `gh` path) — it is what a
+board reader turns into a PR link. If only a compare URL was emitted (no PR yet), drop `--pr`.
 
 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

package/core/hooks/gate.py

@@ -23,7 +23,7 @@ and subagents spawned by the Workflow runtime alike. Workflow subagents run in
 acceptEdits regardless of the session's permission mode (their Write/Edit calls
 are auto-approved), but acceptEdits does NOT auto-approve Bash or Task, so this
 gate still sees and can block them. In bypassPermissions (headless `claude -p`,
-dashboard actions) there is no human to answer a prompt, so every `ask` match is
+unattended workflow runs) there is no human to answer a prompt, so every `ask` match is
 escalated to a hard deny with the reason attached — a clear refusal beats a
 prompt that can never be answered.
 

package/core/workflows/loop.js

@@ -211,6 +211,18 @@ const ITEMS = {
   },
 }
 
+// Token accounting — the one thing the conversational path cannot do (a lead cannot
+// read a subagent's token count) and a workflow can: budget.spent() is the runtime's
+// own output-token counter for this turn. Deltas between marks give an approximate
+// per-phase cost; the review CHILD workflow stamps its own review-phase line, so the
+// loop marks AROUND the child to keep build/fix deltas from double-counting it.
+const spent = () => {
+  try {
+    const v = (budget && typeof budget.spent === 'function') ? budget.spent() : 0
+    return Number.isFinite(v) ? v : 0   // a NaN here would poison every metrics JSON downstream
+  } catch { return 0 }
+}
+
 // kanban-move.sh is optional infrastructure — every prompt that runs it defines <core>
 // and tolerates its absence, per SCHEMA.md §Kanban.
 const CORE_DEF = '(<core> = .claude if .claude/pipeline/scripts/kanban-move.sh exists, else ~/.claude — ' +
@@ -403,6 +415,7 @@ const writeState = async ({ label, phaseName, outcome, reason, status: st, kanba
   if (metrics) steps.push(
     `${steps.length + 1}. Append ONE line to ${METRICS_PATH}: ` +
     `{"ts":"<ISO>","feature":"${feature}","phase":"${metrics.phase}","seconds":$(($(date +%s)-${clock || 0})),` +
+    `"tokens":${metrics.tokens || 0},` +
     `"surfaces":${JSON.stringify(metrics.surfaces)}}` + (metrics.buildJson
       ? `\n${steps.length + 2}. Write to specs/reports/${feature}.build.json (overwrite): ` +
         `{"id":"${feature}","phase":"build","ts":"<ISO>","surfaces":${JSON.stringify(metrics.surfaces)},"dead":${JSON.stringify(metrics.dead)}}`
@@ -434,6 +447,7 @@ const close = async (outcome, reason, extra = {}) => {
   return {
     id: feature, outcome, reason, rounds: history.length,
     blocking: history.length ? history[history.length - 1].blocking : null,
+    tokens: spent(),   // approx output tokens for the whole run (runtime counter)
     history, report: `specs/reports/${feature}.md`,
     ...(closed ? {} : { stateWarning: 'the closing state agent died — loop.json/status/kanban may not reflect this outcome' }),
     ...extra,
@@ -446,6 +460,7 @@ const close = async (outcome, reason, extra = {}) => {
 // build.json is stale, absent, or carries dead[], the loop builds (a full re-dispatch —
 // implementers are idempotent against a frozen contract, the same property fix rounds
 // already rely on).
+let mark = spent()
 if (fresh(facts.build) && !(facts.build.dead || []).length) {
   log('build.json is fresh with no dead surfaces — skipping the build phase, entering at review')
   await writeState({ label: 'state:enter', phaseName: 'review', status: 'in-progress', kanban: 'review' })
@@ -463,7 +478,7 @@ if (fresh(facts.build) && !(facts.build.dead || []).length) {
   await writeState({
     label: 'state:built', phaseName: dead.length ? 'build' : 'review',
     metrics: {
-      phase: 'build', buildJson: true, dead,
+      phase: 'build', buildJson: true, dead, tokens: Math.max(0, spent() - mark),
       surfaces: Object.fromEntries(built.map(b => [b.key, b.handoff == null ? 'dead' : 'ok'])),
     },
   })
@@ -479,6 +494,7 @@ if (fresh(facts.build) && !(facts.build.dead || []).length) {
 while (true) {
   phase('Review')
   await writeState({ label: `state:round-${round}`, phaseName: 'review', status: 'in-progress', kanban: 'review' })
+  const roundMark = spent()
   let review
   try {
     review = await workflow('cohorte-review', { feature })
@@ -489,9 +505,16 @@ while (true) {
     })
   }
 
+  // The review child stamps its own review-phase metrics line; marking here keeps the
+  // fix phase's delta clean of it. History carries the round's review cost.
+  mark = spent()
   const verdict = decide(review, lastKey, round, maxRounds)
   if (review && typeof review.blocking === 'number') {
-    history.push({ round, blocking: review.blocking, fingerprint: hash16((review.blockingItems || []).join('\n')) })
+    history.push({
+      round, blocking: review.blocking,
+      fingerprint: hash16((review.blockingItems || []).join('\n')),
+      tokens: Math.max(0, spent() - roundMark),
+    })
   }
 
   if (verdict.outcome === 'ship') {
@@ -587,7 +610,8 @@ while (true) {
   // exactly the batch worth recording (SCHEMA.md §Dead agents), so it lands before
   // the dead-implementers abort, with the dead surfaces named.
   await writeState({ label: `state:fixed-${round}`, phaseName: 'review', metrics: {
-    phase: 'fix', surfaces: Object.fromEntries(fixed.map(f => [f.key, f.handoff == null ? 'dead' : 'ok'])),
+    phase: 'fix', tokens: Math.max(0, spent() - mark),
+    surfaces: Object.fromEntries(fixed.map(f => [f.key, f.handoff == null ? 'dead' : 'ok'])),
   } })
   if (fixDead.length) {
     // Their items stay `- [ ]` — a dead agent never ticks a box (/cohorte-fix §3), and

package/core/workflows/review.js

@@ -42,6 +42,17 @@ const ARGS = (() => {
   }
   return args && typeof args === 'object' ? args : {}
 })()
+// Approximate cost of this run from the runtime's own output-token counter — the one
+// figure the conversational path cannot record (a lead cannot read a subagent's token
+// count; SCHEMA.md §Measuring cost). Sampled at start, delta stamped into the metrics line.
+const spentNow = () => {
+  try {
+    const v = (budget && typeof budget.spent === 'function') ? budget.spent() : 0
+    return Number.isFinite(v) ? v : 0   // a NaN here would poison the metrics JSON downstream
+  } catch { return 0 }
+}
+const spentStart = spentNow()
+
 const isSlug = s => typeof s === 'string' && /^[A-Za-z0-9._-]+$/.test(s)
 const feature = ARGS.feature
 if (!feature) throw new Error('cohorte-review needs args = {feature: "<feature_id>"}')
@@ -384,10 +395,10 @@ const staging = await agent(
     : 'the blocking list is empty, so <FP> is the empty string "":\n') +
   `${verdictJson}\n` +
   // Per-surface verdicts (not the merged one stamped on every row — one BLOCK used to
-  // mark ALL surfaces failed on the dashboard), and dead reviewers logged as "dead"
+  // mark ALL surfaces failed), and dead reviewers logged as "dead"
   // per SCHEMA.md §Dead agents — an incomplete batch is the batch worth recording.
   `3. Append one line to $(dirname "$(git rev-parse --git-common-dir)")/.claude/pipeline-metrics.jsonl: ` +
-  `{"ts":"<ISO now>","feature":"${feature}","phase":"review","seconds":0,"surfaces":{${
+  `{"ts":"<ISO now>","feature":"${feature}","phase":"review","seconds":0,"tokens":${Math.max(0, spentNow() - spentStart)},"surfaces":{${
     results.map(r => `"${r.key}":"${r.report.verdict}:${r.kept.length}"`)
       .concat(unreviewed.map(k => `"${k}":"dead"`)).join(',')}}}\n` +
   // Deferred findings must land in the backlog on EVERY verdict — parked only on a

package/{dashboard/server → lib}/doctor.js

@@ -1,5 +1,6 @@
 'use strict';
-// Programmatic port of the /cohorte-doctor checks (core/commands/doctor.md), for the dashboard.
+// Programmatic port of the /cohorte-doctor checks (core/commands/cohorte-doctor.md), so
+// `cohorte doctor` can report without a coding agent in the loop.
 // Read-only: inspects files only. Checks that need a live process (MCP connectivity,
 // git worktree state, DesignSync) are reported as `skip` with a note — the node server
 // can't run them, and honest "not checked here" beats a false green.
@@ -247,7 +248,7 @@ function gateRegs(settingsPath, event) {
 
 function checkHooks(projectRoot, globalDir, installMode, all) {
   // A registration can exist without a discoverable core — a repo whose core lives in a global
-  // dir the dashboard was not pointed at, or one predating `runtimes.json`. Falling through to
+  // dir the caller was not pointed at, or one predating `runtimes.json`. Falling through to
   // "no runtime installed" there would hide a real double-registration, so assume the Claude
   // layout: before the adapter it was the only one, and it is the only one whose hook can be
   // registered outside its own core dir.

package/{dashboard/server → lib}/runtime.js

@@ -1,7 +1,7 @@
 'use strict';
 // Which coding agent(s) this project is wired for, and where each one keeps its files.
 //
-// Before 2.2.0 every path in the dashboard was `.claude/…`. That is now one layout of five:
+// Before 2.2.0 every path here was `.claude/…`. That is now one layout of five:
 // a repo driven from Cursor keeps its core in `.cohorte/cursor/`, its agents in
 // `.cursor/agents/` and its gate registration in `.cursor/hooks.json`. Checking the Claude
 // paths there reports a perfectly healthy install as broken — "no core", "no rendered agent",

package/{dashboard/server → lib}/versions.js

@@ -30,12 +30,12 @@ function pointerAt(projectRoot) {
 
 // Latest published version — registry fetch first, `npm view` as a fallback (it uses the
 // user's configured registry/proxy, which works where a raw fetch may be blocked). Cached
-// briefly so the dashboard's poll doesn't hammer the network. null only if both fail.
+// briefly so repeated calls don't hammer the network. null only if both fail.
 let _cache = { value: null, at: 0 };
 const CACHE_MS = 5 * 60 * 1000;
 // Failures are cached too, briefly. Without this an offline machine paid the FULL
 // 5s fetch timeout + 8s `npm view` timeout on every call — and /api/fleet calls
-// this once per tracked project, so the dashboard's 15s poll never finished.
+// this once per tracked project, so a batch of probes never finished.
 const FAIL_CACHE_MS = 60 * 1000;
 
 async function fetchRegistry(timeoutMs = 5000) {

package/package.json

@@ -1,26 +1,21 @@
 {
   "name": "cohorte",
-  "version": "2.8.0",
+  "version": "2.10.0",
   "description": "Portable, stack-agnostic multi-agent development pipeline for Claude Code, Codex CLI, Cursor, Gemini CLI and OpenCode — install the core, run /cohorte-init-pipeline, and it adapts to your project's stack.",
   "bin": {
     "cohorte": "bin/cli.js"
   },
-  "scripts": {
-    "build:dashboard": "npm --prefix dashboard/app ci && npm --prefix dashboard/app run build",
-    "prepack": "npm run build:dashboard"
-  },
   "files": [
     "bin",
+    "lib",
     "core",
     "profile",
     "scripts",
     "!scripts/new-feature.sh",
     "!scripts/remove-feature.sh",
+    "!scripts/demo",
     "!core/hooks/__pycache__",
     "!**/*.pyc",
-    "dashboard/server",
-    "dashboard/dist",
-    "dashboard/README.md",
     "install.sh",
     "install.ps1",
     "CHANGELOG.md"

package/profile/SCHEMA.md

@@ -176,7 +176,7 @@ the **main checkout's** `<state>/pipeline-metrics.jsonl` (gitignored) — one JS
 and `/cohorte-fix`.
 **`surfaces` keys are surface keys, nothing else** — run-level facts go in their own top-level
 fields. Anything put inside `surfaces` is read
-as a surface: the dashboard renders it as a row in the per-surface table and scores a non-`ok`
+as a surface: `cohorte doctor` renders it as a row in the per-surface table and scores a non-`ok`
 value as that surface failing. Always the main checkout, never the feature worktree (which dies at teardown while
 metrics must accumulate across features) — resolve from anywhere with
 `$(dirname "$(git rev-parse --git-common-dir)")/<state>/pipeline-metrics.jsonl`. Read it before
@@ -185,8 +185,13 @@ proposing a split: split the surface that actually dominates wall-clock, not the
 ## Measuring cost — what's slow vs what's expensive
 
 `pipeline-metrics.jsonl` records **wall-clock seconds** per phase batch (§Specialization) — it tells you
-what's SLOW. It deliberately does NOT record tokens: the lead can't reliably read a subagent's token count
-to log it. For what's EXPENSIVE, use Claude Code's own accounting:
+what's SLOW. Tokens are recorded only where they can be read honestly: the **workflow paths**
+(`loop.js`, `review.js`) stamp an approximate `tokens` field per batch from the runtime's own
+counter (`budget.spent()` deltas), and the loop's return carries a per-round breakdown in its
+`history`. The **conversational** commands still record none — a lead cannot reliably read a
+subagent's token count, and a guessed number is worse than a missing one. `cohorte metrics` sums
+whatever is stamped (a token-less line aggregates as 0, rendered as absent, never as "free").
+For exact spend, use Claude Code's own accounting:
 
 - **`/cost`** (built-in, zero setup) — reports per-**subagent** and per-**slash-command** share of your usage
   over the last 24 h / 7 d (e.g. _"Top subagents: frontend 7 %, backend 4 % · Top skills: /cohorte-build 1 %,
@@ -226,7 +231,7 @@ storing a bare `pnpm test` as the thing agents execute; `/cohorte-update-pipelin
 ## Spec status — the lifecycle state machine
 
 A spec's front-matter `status` is not a label, it is the pipeline's **state**: every command routes on
-it, the dashboard boards on it, and the kanban backfill maps it to a column. Six states:
+it, `cohorte specs` boards on it, and the kanban backfill maps it to a column. Six states:
 
 | status | meaning | written by | who may build it |
 | --- | --- | --- | --- |
@@ -352,18 +357,21 @@ project has *decided*. Without somewhere for those, every `/cohorte-spec` re-dis
 `specs/_decisions.md` (from `core/templates/decisions.template.md`) is that place, deliberately small:
 
 - **Append-only, one line per decision, ≤ ~160 chars:**
-  `- <YYYY-MM-DD> · <area> · <decision> — because <reason> · <feature_id>`. Reversal never edits a line:
+  `- <YYYY-MM-DD> · <area> · <decision> — because <reason> · <origin>`, where `<origin>` is the
+  `feature_id` that decided it — or the originating command (`retro`) when no single feature owns
+  it. Reversal never edits a line:
   append a superseding one (`· supersedes <date> <area>`) and move the old one to `## Superseded`. When
   `## Live` passes ~100 lines, sweep the superseded ones down.
 - **Written by** `/cohorte-spec` at freeze (the decisions that outlive the feature — typically 0–3 lines, and
-  zero is a normal outcome) and `/cohorte-build` §1.5 when it adds or splits a surface.
+  zero is a normal outcome), `/cohorte-build` §1.5 when it adds or splits a surface, and
+  `/cohorte-retro` §4 when the human ratifies a convention rule (one line per adopted rule).
 - **Read by the deciding stages only** — `/cohorte-brainstorm` (so the panel argues about the idea, not about
   settled ground), `/cohorte-spec` (so a new spec does not silently un-decide something), `/cohorte-audit` (standing
   decisions are part of the rulebook it audits against).
 - **Never read by implementers or reviewers.** They work from the frozen contract, which already tells
   them what to do; shipping them the rationale would cost `surfaces × dispatches` tokens per feature
   for a fact they cannot act on. This is what keeps the journal cheap enough to be worth having.
-- The `_` prefix is load-bearing: `/cohorte-doctor`, the dashboard spec scanner and the kanban backfill all skip
+- The `_` prefix is load-bearing: `/cohorte-doctor`, the `cohorte specs` scanner and the kanban backfill all skip
   `specs/_*.md`, so the journal is never mistaken for a spec (no phantom card, no bogus stage).
 
 ## Preflight — the deterministic phase gate
@@ -618,7 +626,7 @@ notes a human writes as sub-bullets under an Ideas card are seed context for `/c
 the trailing `%% kanban:settings … %%` block or the `kanban-plugin: board` front-matter.
 
 Once shipped, `/cohorte-ship` appends the **PR number** to the card — `- [ ] <title> #<feature_id> — PR #<num>`.
-The bare `#<num>` is what the dashboard renders as a clickable link to the GitHub PR, so `/cohorte-ship` always
+The bare `#<num>` is what a board reader 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).** One call — the script does resolution AND the move outside the