cohorte 2.3.0 → 2.5.0

package/CHANGELOG.md

@@ -7,6 +7,77 @@ 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.5.0 — 2026-08-14
+
+- **Everything the pipeline knew about your repo, it would only say to a coding agent.**
+  `/cohorte-doctor` reads the health of an install and `specs/*.md` holds the board, but both
+  answers cost a session: you opened Claude Code, ran a command, and read prose. There was no
+  way to ask "is this repo's pipeline sound?" from a shell script, a CI job, or anything that
+  isn't an LLM.
+
+  Two read-only commands now answer without an agent in the loop:
+
+  ```sh
+  cohorte specs     # the board: id · status · branch · title, from specs/*.md frontmatter
+  cohorte doctor    # the /cohorte-doctor checks — exits 1 when any check is bad
+  ```
+
+  `doctor` **exits 1 on any bad check**, so it drops into CI as-is. Both reuse the dashboard's
+  own readers, so the board, the dashboard and the CLI can never give three answers about one
+  repo. `--porcelain` gives one record per line with `U+001F` between fields — a spec title
+  with a space in it never misaligns a column — and `--json` gives the native document.
+
+- **The pipeline, in Francois.** A third shape, `--panel` (on `specs`, `doctor` and `metrics`),
+  emits the payload a [Francois](https://github.com/antoine-gmnz/francois) extension panel
+  validates against. It exists for
+  [**francois-plugin-cohorte**](https://github.com/TheBidouilleAgency/francois-plugin-cohorte):
+  a manifest-only extension — no code, no binary — that renders the 30-day cost, the doctor
+  report and the spec board as three panels beside your sessions, on any project with a
+  `PIPELINE.md`.
+
+  ```sh
+  npm i -g cohorte                                   # a Francois extension may only spawn a
+  francois ext install TheBidouilleAgency/cohorte    # bare binary on PATH — never npx, never a shell
+  ```
+
+  This is the only Francois-aware surface in the package, and it is one flag wide. Nothing in
+  the pipeline itself changed: no new agent, no new gate, no template to re-render — this
+  release needs no `/cohorte-update-pipeline`.
+
+## 2.4.0 — 2026-08-13
+
+- **The pipeline froze *what* to build, never *how much*.** A spec pins the contract and the
+  acceptance criteria, so the feature was right — but nothing ever asked an implementer whether the
+  helper it was about to write already existed three files over, whether the stdlib shipped it, or
+  whether the abstraction it was wrapping had exactly one caller. The diff came out correct and
+  fatter than it needed to be, and every extra line was then paid twice: once at build, once again at
+  `/cohorte-review`, whose cost is linear in the diff it reads.
+
+  Implementers now walk a **minimality ladder** before inventing anything: does it need to exist at
+  all → already in this repo → stdlib/framework → native platform feature → an already-installed
+  dependency → a few inline lines → only then the minimum the contract requires. It governs the
+  **how**, never the **what** — a contract field, an acceptance criterion, a test, a validation or an
+  authz check is out of its reach, by construction. It is bounded to **one lookup per candidate**, so
+  it costs a symbol search and not an exploration, and a shortcut kept on purpose surfaces in the
+  handoff's `## TODO / not done` with its ceiling and its upgrade trigger, instead of rotting in a
+  comment.
+
+  The `review` agent gains the matching axis — over-engineering, tagged `delete:` / `stdlib:` /
+  `native:` / `yagni:` / `shrink:`, always naming the cheaper replacement. It is deliberately the
+  weakest thing in the report: **5 findings max, MEDIUM ceiling, never a CRITICAL, never a REVISE,
+  never a BLOCK**. A diff whose only findings are `complexity` ships, and they park in the backlog
+  like any other nit. Tests, fixtures and anything the contract mandates are out of bounds — coverage
+  is not bloat. In audit mode the axis widens to the whole target (10 per domain, biggest cut first,
+  closing with `net: -N lines, -M deps possible.`), and `/cohorte-audit` files them under a new
+  `complexity` backlog tag: the cheapest wins in the file, since deleting code needs no new test.
+
+  Doctrine adapted from [ponytail](https://github.com/dietrichgebert/ponytail) (MIT) — the decision
+  ladder and the finding tags are theirs; the subordination to the frozen contract and the
+  can't-block severity ceiling are what make them safe inside a gated pipeline.
+
+  Run `/cohorte-update-pipeline` to re-render your surface agents — the ladder lives in the
+  implementer template, so it only reaches your agents through a reconcile.
+
 ## 2.3.0 — 2026-08-12
 
 - **A bug fix had to pretend to be a feature.** The only way into the pipeline was

package/README.md

@@ -234,6 +234,33 @@ source lives in `dashboard/app/`, built to `dashboard/dist/` at publish time). T
 are reimplemented in JS, so the dashboard needs no Claude session to compute state. See
 [`dashboard/README.md`](dashboard/README.md) for the architecture.
 
+## Reading a project without an agent
+
+The two read-only halves of the pipeline, in the shell:
+
+```sh
+npx cohorte specs              # the board: id · status · branch · title, from specs/*.md
+npx cohorte doctor             # the /cohorte-doctor checks — exits 1 when any check is bad
+npx cohorte metrics --days=30  # cost + runtime per command, from Claude Code's transcripts
+```
+
+`doctor`'s exit code makes it a CI step as-is. Add `--porcelain` for one record per line with
+`U+001F` between fields (a spec title with a space in it never misaligns a column), or `--json`
+for the native document. Both reuse the dashboard's own readers, so the board and the CLI can
+never give two answers about one repo.
+
+`--panel` — on `specs`, `doctor` and `metrics` — emits the payload shape a
+[Francois](https://github.com/antoine-gmnz/francois) extension panel expects. It is the one
+Francois-aware surface in the package, and it exists for
+[**francois-plugin-cohorte**](https://github.com/TheBidouilleAgency/francois-plugin-cohorte): a
+manifest-only extension that renders the spec board, the doctor report and the 30-day cost as
+three panels beside your sessions.
+
+```sh
+npm i -g cohorte                              # a Francois extension may only spawn a bare
+francois ext install TheBidouilleAgency/cohorte   # binary on PATH — never npx, never a shell
+```
+
 ## Releasing (maintainers)
 
 Versions are tracked with npm semver — the published package is the release artifact.

package/bin/cli.js

@@ -37,6 +37,8 @@ Usage:
   cohorte update    [target] [--global] [--runtime=a,b | --all-runtimes]
   cohorte dashboard [target] [--port=N] [--host=ADDR] [--open]
   cohorte metrics   [target] [--days=N] [--since=ISO] [--runs] [--json]
+  cohorte specs     [target] [--porcelain | --json | --panel]
+  cohorte doctor    [target] [--porcelain | --json | --panel]
   cohorte version
 
 Commands:
@@ -56,8 +58,18 @@ Commands:
             ~/.claude/projects — nothing to enable, and it covers runs that
             already happened. Worktree-aware, so a feature adds up. --json for
             the raw rollup, --runs to include every individual invocation.
+  specs     The spec board of <target>: id, status, branch, title, read from the
+            frontmatter of specs/*.md. --porcelain for one record per line with
+            U+001F between fields, --json for the list.
+  doctor    The same checks /cohorte-doctor runs (core, pointer, profile, agents,
+            hook, gate, retrieval, design, isolation, specs), without a coding
+            agent in the loop. Exits 1 when any check is bad, 0 otherwise, so it
+            drops into CI. --porcelain / --json as above.
   version   Print the installed CLI version.
 
+  --panel on specs, doctor and metrics emits the payload a Francois extension
+  panel expects (github.com/TheBidouilleAgency/francois-plugin-cohorte).
+
 Runtimes (--runtime=): ${adapter.listRuntimes().join(', ')}
   The pipeline's doctrine is one set of source prompts; the installer renders them into
   whatever each coding agent reads (markdown + frontmatter, plain markdown, or TOML) and
@@ -86,13 +98,19 @@ const metricsFlags = [];
 const isMetricsFlag = (a) =>
   a === '--json' || a === '--runs' || a.startsWith('--days=') || a.startsWith('--since=');
 
+// How `specs`, `doctor` and `metrics` render. One variable, not one flag per command,
+// so `--porcelain` never means two different things depending on where it sits.
+let format = 'human';
+
 // Which coding agents to install for. Empty ⇒ resolved later (detect, then ask on a TTY,
 // then fall back to claude — the only behaviour that existed before 2.2.0).
 let wantRuntimes = [];
 
 for (const a of args) {
-  if (a === 'install' || a === 'update' || a === 'dashboard' || a === 'metrics') mode = a;
-  else if (isMetricsFlag(a)) metricsFlags.push(a);
+  if (a === 'install' || a === 'update' || a === 'dashboard' || a === 'metrics'
+      || a === 'specs' || a === 'doctor') mode = a;
+  else if (a === '--porcelain' || a === '--panel') format = a.slice(2);
+  else if (isMetricsFlag(a)) { if (a === '--json') format = 'json'; metricsFlags.push(a); }
   else if (a === '--all-runtimes') wantRuntimes = adapter.listRuntimes();
   else if (a === '--runtimes' || a === '--runtime') {
     console.error('error: --runtime needs a value, e.g. --runtime=codex,cursor'); process.exit(2);
@@ -136,10 +154,45 @@ if (mode === 'dashboard') {
   return;
 }
 
+// --- specs / doctor: read-only reports on <target> ---------------------------
+// Both reuse the dashboard's own readers, so the board and the CLI can never drift
+// into two answers about the same repo. Nothing here writes or spawns anything.
+if (mode === 'specs' || mode === 'doctor') {
+  const report = require('./report.js');
+  const { state, scanSpecs } = require('../dashboard/server/doctor.js');
+  const globalDir = process.env.CLAUDE_CONFIG_DIR || path.join(os.homedir(), '.claude');
+
+  if (mode === 'specs') {
+    const records = report.specRecords(target, scanSpecs);
+    if (format === 'json') console.log(JSON.stringify({ project: target, specs: records }, null, 2));
+    else if (format === 'porcelain') { if (records.length) console.log(report.specsPorcelain(records)); }
+    else if (format === 'panel') console.log(report.specsPanel(records));
+    else console.log(report.specsHuman(records));
+    process.exit(0);
+  }
+
+  // `state` is async (it probes versions), so this branch owns the whole tail.
+  state({ projectRoot: target, globalDir, cliVersion: VERSION }).then((s) => {
+    const records = report.checkRecords(s);
+    if (format === 'json') console.log(JSON.stringify(s, null, 2));
+    else if (format === 'porcelain') { if (records.length) console.log(report.doctorPorcelain(records)); }
+    else if (format === 'panel') console.log(report.doctorPanel(records));
+    else console.log(report.doctorHuman(s, records));
+    // A bad check is a failure the shell can branch on; warn and skip are not.
+    process.exit(s.summary.bad > 0 && format !== 'panel' ? 1 : 0);
+  }).catch((e) => {
+    console.error(`error: ${e && e.message ? e.message : e}`);
+    process.exit(1);
+  });
+  return;
+}
+
 // --- metrics: cost + runtime per command ------------------------------------
 // The collector is ESM and this CLI is CommonJS, so it runs as a child process rather
 // than being required. stdio is inherited so --json stays pipeable.
 if (mode === 'metrics') {
+  // `--panel` is not in isMetricsFlag (it is not metrics-specific), so forward it here.
+  if (format === 'panel') metricsFlags.push('--panel');
   const script = path.join(pkgRoot, 'scripts', 'metrics', 'collect.mjs');
   if (!fs.existsSync(script)) {
     console.error(`error: metrics collector not found at ${script}`);

package/bin/report.js

@@ -0,0 +1,141 @@
+'use strict';
+// Machine-readable reports for `cohorte specs` and `cohorte doctor`.
+//
+// Both commands read what the dashboard already computes (dashboard/server/doctor.js:
+// `scanSpecs` and `state`) and render it four ways:
+//
+//   default      a human table on a terminal
+//   --porcelain  one record per line, fields separated by U+001F (the ASCII unit
+//                separator) — stable, greppable, and immune to a spec title that
+//                contains a space, a tab or a pipe
+//   --json       the native document (the full doctor state, the spec list)
+//   --panel      the payload shape a Francois extension panel validates against
+//                (`{rows:[{key,value,tone}]}` / `{rows:[{id,cells,tone}]}`). This is
+//                the ONLY Francois-aware surface in cohorte; everything else here is
+//                generic. See github.com/TheBidouilleAgency/francois-plugin-cohorte.
+//
+// Dependency-free, and it never writes anything.
+
+const US = String.fromCharCode(0x1f); // ASCII unit separator (U+001F)
+
+// A spec's status → a display tone. The tones are the ones a status column can carry
+// anywhere (terminal colour, panel row tone); `busy` marks the two statuses that mean
+// "a command is mid-flight on this spec".
+const STATUS_TONE = {
+  draft: 'neutral',
+  frozen: 'neutral',
+  'in-progress': 'busy',
+  'in-review': 'busy',
+  shipped: 'ok',
+  blocked: 'error',
+};
+
+// doctor's four check states → the same tone vocabulary. `skip` is not a failure:
+// a check that does not apply to this project (no design system, no worktrees) reads
+// neutral, never warn.
+const CHECK_TONE = { ok: 'ok', warn: 'warn', bad: 'error', skip: 'neutral' };
+
+// Collapse anything that would break the line format or a single-line cell. A spec
+// title is free text written by a human in YAML frontmatter — it can contain a newline
+// continuation, and it must never split one record into two. A stray separator inside a
+// field goes the same way, and so does the padding a doctor `fix` carries for terminal
+// alignment — in a one-line panel cell that padding reads as a hole.
+function flat(value) {
+  return String(value == null ? '' : value)
+    .replace(new RegExp(`[\\s${US}]+`, 'g'), ' ')
+    .trim();
+}
+
+function specRecords(projectRoot, scanSpecs) {
+  return scanSpecs(projectRoot).map((s) => ({
+    id: s.id,
+    title: s.title || '',
+    status: s.status || 'unknown',
+    branch: s.branch || '',
+    file: s.file,
+    tone: STATUS_TONE[s.status] || 'warn', // an unknown status IS the warning
+  }));
+}
+
+function specsPorcelain(records) {
+  return records
+    .map((r) => [r.id, r.title, r.status, r.branch, r.tone].map(flat).join(US))
+    .join('\n');
+}
+
+function specsPanel(records) {
+  return JSON.stringify({
+    rows: records.map((r) => ({
+      id: flat(r.id),
+      tone: r.tone,
+      cells: { id: flat(r.id), title: flat(r.title), status: flat(r.status), branch: flat(r.branch) },
+    })),
+  });
+}
+
+function specsHuman(records) {
+  if (!records.length) return 'no specs in ./specs — /cohorte-spec writes the first one';
+  const w = (k) => Math.max(...records.map((r) => flat(r[k]).length), k.length);
+  const [wi, ws, wb] = [w('id'), w('status'), w('branch')];
+  const head = `${'id'.padEnd(wi)}  ${'status'.padEnd(ws)}  ${'branch'.padEnd(wb)}  title`;
+  const rows = records.map(
+    (r) => `${flat(r.id).padEnd(wi)}  ${flat(r.status).padEnd(ws)}  ${flat(r.branch).padEnd(wb)}  ${flat(r.title)}`,
+  );
+  return [head, '-'.repeat(head.length), ...rows].join('\n');
+}
+
+function checkRecords(state) {
+  return state.checks.map((c) => ({
+    id: c.id,
+    label: c.label,
+    status: c.status,
+    detail: c.detail,
+    fix: c.fix || '',
+    tone: CHECK_TONE[c.status] || 'neutral',
+  }));
+}
+
+function doctorPorcelain(records) {
+  return records
+    .map((r) => [r.id, r.label, r.status, r.detail, r.fix].map(flat).join(US))
+    .join('\n');
+}
+
+// key-value, one row per check: the check's label keyed against what it found. The fix
+// rides in the value for a failing check — a panel row has nowhere else to put it, and
+// a health report that says "broken" without saying "run this" is half a report.
+function doctorPanel(records) {
+  return JSON.stringify({
+    rows: records.map((r) => ({
+      key: flat(r.label),
+      value: flat(r.fix && r.tone !== 'ok' ? `${r.detail} → ${r.fix}` : r.detail),
+      tone: r.tone,
+    })),
+  });
+}
+
+function doctorHuman(state, records) {
+  const mark = { ok: 'ok  ', warn: 'warn', bad: 'BAD ', skip: 'skip' };
+  const lines = [`cohorte doctor — ${state.project}`, ''];
+  for (const r of records) {
+    lines.push(`${mark[r.status] || '?   '}  ${r.label} — ${flat(r.detail)}`);
+    if (r.fix && r.status !== 'ok') lines.push(`        fix: ${flat(r.fix)}`);
+  }
+  const s = state.summary;
+  lines.push('', `${s.ok} ok · ${s.warn} warn · ${s.bad} bad · ${s.skip} skipped`);
+  return lines.join('\n');
+}
+
+module.exports = {
+  US,
+  STATUS_TONE,
+  CHECK_TONE,
+  specRecords,
+  specsPorcelain,
+  specsPanel,
+  specsHuman,
+  checkRecords,
+  doctorPorcelain,
+  doctorPanel,
+  doctorHuman,
+};

package/core/agents/implementer.template.md

@@ -59,6 +59,33 @@ them over Grep/Glob + whole-file Reads**: locate code by symbol, read only the d
 and trace references before changing any shared shape. Fall back to Grep/Read only when the retrieval
 tools are unavailable or come up empty.
 
+## How you choose what to write — the minimality ladder
+
+The spec froze the **what**; this ladder governs only the **how**. It never licenses you to skip a
+contract field, an acceptance criterion, a test, a validation, an authz check or an accessibility
+attribute — those are the *what*, and they are not yours to trim.
+
+Before writing any helper, utility, wrapper, abstraction or new dependency, walk down and stop at the
+first hit:
+
+1. **Does it need to exist at all?** An abstraction with one implementation, a config nobody sets, a
+   layer with one caller — don't write it. The second caller is when it earns its keep.
+2. **Is it already in this repo?** One retrieval/Grep lookup by symbol name, not a survey — you are
+   checking, not exploring. Reuse beats re-implementing, and it keeps the convention.
+3. **Is it in the standard library / framework?** Name it and use it.
+4. **Is it a native platform feature?** (CSS, the HTTP layer, the DB, the runtime.) Prefer it over code.
+5. **Is it in a dependency already installed?** Use that one. Adding a dependency for what tiers 3–5
+   already ship is a finding at review.
+6. **Can it be a few lines inline?** Then it doesn't need a file, a class, or a name.
+7. Only then: the **minimum implementation that satisfies the contract** — no speculative options, no
+   "we'll probably need" parameters, no premature generalisation.
+
+Bound the cost: this is at most **one lookup per candidate**, and it applies to code you are inventing —
+never to code the contract dictates. If a step would cost more searching than writing, write it.
+
+Something you deliberately kept simple with a known ceiling goes in your handoff `## TODO / not done`
+with its limit and what would trigger the upgrade — not in a comment, and not silently.
+
 ## How you work — strict TDD (red → green → refactor)
 
 <!-- <SURFACE_TDD_STEP1> is a LEAD-IN paragraph, not a numbered item: it is filled only for a

package/core/agents/review.md

@@ -63,6 +63,20 @@ be precise and self-contained.
    additive `sm:/md:/lg:`, no fixed widths that break on mobile. (You can't render; judge from the code.)
 7. **TDD coverage.** Each surface's tests cover its slice of the contract (statuses, validation, auth,
    behavior). Flag untested contract surface.
+8. **Over-engineering (lowest priority, never blocking).** Code the diff *added* that didn't need to
+   exist. Tag each one and always name the replacement — a finding with no cheaper alternative is an
+   opinion, not a finding:
+   - `delete:` dead code, unused flexibility, a speculative feature nothing calls. Replacement: nothing.
+   - `stdlib:` hand-rolled thing the standard library or framework ships. Name the function.
+   - `native:` a dependency or code doing what the platform already does. Name the feature.
+   - `yagni:` abstraction with one implementation, config nobody sets, layer with one caller.
+   - `shrink:` same behaviour, materially fewer lines. Name the shorter form.
+
+   **Hard limits on this axis.** It is capped at **5 findings**, biggest cut first, and its severity
+   ceiling is **MEDIUM** — it can never produce CRITICAL, never REVISE, never BLOCK. Test code,
+   fixtures and anything the contract or an acceptance criterion mandates are **out of bounds**:
+   coverage is not bloat, and "simpler" is never a reason to drop a spec'd behaviour. Deduplication
+   that would cross a surface boundary is out of bounds too — that's an architecture call, not a review one.
 
 ## Language checks (apply only those matching the surfaces under review)
 
@@ -89,10 +103,19 @@ entry point / module with **no test**), and the lint/format/type debt staged at
 dispatch names (`specs/reports/audit-gates.txt`). Emit a **prioritized refactor backlog grouped by
 domain** (same finding-line shape) instead of a SHIP/REVISE/BLOCK verdict.
 
+In audit mode the over-engineering axis (§8) widens: there is no diff, so the whole target is in
+scope and the 5-finding cap lifts to **10 per domain**, ranked biggest cut first. Hunt the usual
+shapes — deps the stdlib or platform already ships, single-implementation interfaces, factories with
+one product, wrappers that only delegate, dead flags and config, hand-rolled stdlib. Close the
+audit-mode report with one line: `net: -<N> lines, -<M> deps possible.` (`0`/`0` is a valid answer —
+say it rather than inventing cuts).
+
 ## Severity & verdict
 
 - **CRITICAL** — spec violation or correctness bug that must be fixed ⇒ verdict **REVISE**.
 - **HIGH / MEDIUM / LOW** — quality/convention issues; note them.
+- **Over-engineering (§8) caps at MEDIUM** and never drives the verdict — a diff whose only findings
+  are `complexity` ships. It is a cleanup signal, not a gate.
 - Any **security vulnerability** ⇒ verdict **BLOCK**.
 - No CRITICAL and no security issue ⇒ verdict **SHIP**.
 
@@ -117,7 +140,7 @@ they are **never lost and never cost a fix loop**.
 ## Your return — the REVIEW REPORT, exactly this shape
 
 Every finding must be **self-sufficient for a stateless agent**: `file:line` · severity ·
-`spec-violation | quality | security` · one concrete suggested fix — it gets appended verbatim to the
+`spec-violation | quality | security | complexity` · one concrete suggested fix — it gets appended verbatim to the
 spec's `## Remediation`. Your final message **is** the report. **The shape is capped:** at most
 **20 findings**, ONE line each, **zero code excerpts** (the diff and the source are on disk — a
 `file:line` is enough for a stateless fixer). More than 20? Keep every CRITICAL/HIGH/security
@@ -140,12 +163,13 @@ Verdict: <SHIP | REVISE | BLOCK>
 
 ## Findings
 
-- **[<SEVERITY>]** `<file>:<line>` · <spec-violation|quality|security> · <problem> → **Fix:** <concrete change>
-(order by severity; "None." if none; max 20 lines, one per finding, no code excerpts)
+- **[<SEVERITY>]** `<file>:<line>` · <spec-violation|quality|security|complexity> · <problem> → **Fix:** <concrete change>
+(order by severity; "None." if none; max 20 lines, one per finding, no code excerpts.
+ `complexity` lines carry their §8 tag in the problem — `yagni: <what>` — and cap at 5)
 
 ## Deferred
 
-- **[<SEVERITY>]** `<file>:<line>` · <quality|security> · <problem> → **Fix:** <concrete change> · out of scope: <why this feature does not own it>
+- **[<SEVERITY>]** `<file>:<line>` · <quality|security|complexity> · <problem> → **Fix:** <concrete change> · out of scope: <why this feature does not own it>
 (real but out of this feature's scope — see §Deferred; worst first; "None." if none; max 10 lines)
 
 ## Notes

package/core/commands/cohorte-audit.md

@@ -32,8 +32,9 @@ bulk never sits in your history, then grep it for the `file:line` of every failu
 
 Dispatch `review` (read-only; static prompt first, variable slot last — prompt-cache prefix):
 "Audit a target against `PIPELINE.md` (no spec — **audit mode**). Check conventions (§Conventions
-per surface), TDD coverage (untested entry points / modules per surface), and — if the profile
-enables them — mobile-first + design-system usage. Mechanical findings from the gates: read
+per surface), TDD coverage (untested entry points / modules per surface), over-engineering (§8,
+widened per your audit-mode rules — ranked biggest cut first, closing `net:` line), and — if the
+profile enables them — mobile-first + design-system usage. Mechanical findings from the gates: read
 `specs/reports/audit-gates.txt`. Emit a prioritized refactor backlog (capped finding-line format
 from your instructions), grouped by domain (one group per surface + shared). — Target: `$ARGUMENTS`
 (default: whole repo)."
@@ -42,7 +43,11 @@ from your instructions), grouped by domain (one group per surface + shared). —
 
 Merge mechanical + convention findings into one prioritized backlog and **write
 `specs/refactor-backlog.md`**, grouped by domain, each item:
-`- [ ] <SEVERITY> · <file:line> · <rule|tdd|lint|format|type|security> · <concrete fix>`
+`- [ ] <SEVERITY> · <file:line> · <rule|tdd|lint|format|type|security|complexity> · <concrete fix>`
+
+`complexity` items are the over-engineering cuts, ranked biggest first inside their domain — they are
+the cheapest wins in the backlog (deleting code needs no new tests) but they never outrank a
+security, correctness or `tdd` item.
 
 **Carry over the deferred items** before overwriting: `grep -n 'deferred:' specs/refactor-backlog.md`
 and re-emit every **open** (`- [ ]`) match verbatim under its domain, tag included. Those lines were

package/core/commands/cohorte-review.md

@@ -165,7 +165,7 @@ exactly the leak this step closes. Append each merged `## Deferred` item to
 `/cohorte-refactor <domain>` picks them up with no extra plumbing):
 
 ```
-- [ ] <SEVERITY> · <file:line> · <quality|security|rule> · <concrete fix> · deferred:$ARGUMENTS
+- [ ] <SEVERITY> · <file:line> · <quality|security|rule|complexity> · <concrete fix> · deferred:$ARGUMENTS
 ```
 
 - **Never into the spec's `## Remediation`** — that list is what `/cohorte-fix` re-dispatches, so a

package/core/workflows/review.js

@@ -125,7 +125,7 @@ const FINDING = {
   properties: {
     severity: { enum: ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'] },
     file: { type: 'string' }, line: { type: 'integer' },
-    kind: { enum: ['spec-violation', 'quality', 'security'] },
+    kind: { enum: ['spec-violation', 'quality', 'security', 'complexity'] },
     problem: { type: 'string', description: 'one line, no code excerpts' },
     fix: { type: 'string', description: 'one concrete change, one line' },
   },
@@ -141,7 +141,7 @@ const DEFERRED = {
   properties: {
     severity: { enum: ['CRITICAL', 'HIGH', 'MEDIUM', 'LOW'] },
     file: { type: 'string' }, line: { type: 'integer' },
-    kind: { enum: ['quality', 'security', 'rule'] },
+    kind: { enum: ['quality', 'security', 'rule', 'complexity'] },
     problem: { type: 'string', description: 'one line, no code excerpts' },
     fix: { type: 'string', description: 'one concrete change, one line' },
     outOfScope: { type: 'string', description: 'one line: why this feature does not own it' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cohorte",
-  "version": "2.3.0",
+  "version": "2.5.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"

package/scripts/metrics/collect.mjs

@@ -481,6 +481,22 @@ function main(argv) {
     agents: rows.reduce((n, r) => n + r.agents.total, 0),
   };
 
+  // The headline figures as a Francois extension `stat-row` payload — four tiles, no
+  // table. Deliberately ahead of the --json branch: --panel is a shape, not a filter,
+  // and passing both should never print two documents.
+  // See github.com/TheBidouilleAgency/francois-plugin-cohorte.
+  if (flag('panel')) {
+    const window = opt('days') ? `last ${opt('days')} days` : since ? 'since ' + new Date(since).toISOString().slice(0, 10) : 'all time';
+    const top = rows[0];
+    process.stdout.write(JSON.stringify({ tiles: [
+      { label: 'Cost', value: fmtUsd(totals.cost), sublabel: window },
+      { label: 'Runs', value: String(totals.runs), sublabel: `${totals.sessions} sessions` },
+      { label: 'Subagents', value: String(totals.agents) },
+      ...(top ? [{ label: 'Priciest', value: top.command, sublabel: fmtUsd(top.cost.total) }] : []),
+    ] }) + '\n');
+    return 0;
+  }
+
   if (flag('json')) {
     const out = { generatedAt: new Date().toISOString(), projectRoot: root,
                   checkouts: [...checkouts], pricesUpdated: PRICES.updated, totals, commands: rows };