cohorte 2.4.0 → 2.5.0

package/CHANGELOG.md

@@ -7,6 +7,43 @@ 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

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/package.json

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