cohorte 2.10.0 → 3.0.0-dev.0

package/lib/runtime.js

@@ -1,134 +0,0 @@
-'use strict';
-// Which coding agent(s) this project is wired for, and where each one keeps its files.
-//
-// 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",
-// "gate not registered" — which is worse than not checking at all: it sends a human fixing
-// something that is not wrong.
-//
-// The installer writes `<core>/pipeline/runtimes.json` (a map of every runtime installed
-// against that core), so discovery is a directory probe rather than a guess.
-
-const fs = require('fs');
-const os = require('os');
-const path = require('path');
-
-function readJson(file) {
-  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
-}
-
-// `<state>` — where the pipeline writes what it generates FOR THIS PROJECT (gate config,
-// preflight stamp, metrics). Shared by every non-Claude runtime on purpose: it describes the
-// project, not the agent driving it.
-function stateDirFor(id) {
-  return id === 'claude' ? '.claude' : '.cohorte';
-}
-
-// Candidate core directories, project scope first — a bundled core wins over a global one,
-// same precedence the commands themselves use.
-function candidateCores(projectRoot, globalDir) {
-  const home = os.homedir();
-  const out = [
-    { dir: path.join(projectRoot, '.claude'), scope: 'project' },
-    { dir: globalDir || path.join(home, '.claude'), scope: 'global' },
-  ];
-  for (const [root, scope] of [[path.join(projectRoot, '.cohorte'), 'project'],
-                               [path.join(home, '.cohorte'), 'global']]) {
-    let entries = [];
-    try { entries = fs.readdirSync(root, { withFileTypes: true }); } catch { /* absent */ }
-    for (const e of entries) {
-      if (e.isDirectory()) out.push({ dir: path.join(root, e.name), scope });
-    }
-  }
-  return out;
-}
-
-/**
- * Every runtime installed against this project, most-authoritative first.
- * Each layout resolves the paths a check needs, absolute where they are absolute.
- * Returns [] when nothing is installed — callers report that as the missing core it is.
- */
-function layouts({ projectRoot, globalDir }) {
-  const found = [];
-  const seen = new Set();
-  for (const { dir, scope } of candidateCores(projectRoot, globalDir)) {
-    const registry = readJson(path.join(dir, 'pipeline', 'runtimes.json'));
-    // A core with no registry predates the adapter ⇒ it can only be a Claude install.
-    const ids = registry ? Object.keys(registry) : (
-      fs.existsSync(path.join(dir, 'pipeline', 'VERSION')) ? ['claude'] : []);
-    for (const id of ids) {
-      const key = `${id}@${dir}`;
-      if (seen.has(key)) continue;
-      seen.add(key);
-      const rec = (registry && registry[id]) || {};
-      const p = rec.paths || {};
-      // runtimes.json records ABSOLUTE install-time paths. For a bundled (committed)
-      // core, a clone or a moved checkout still carries the ORIGINAL machine's paths —
-      // taken verbatim, every doctor check goes red on a healthy install ("no rendered
-      // agent", "gate not registered"). Recover the install-time project root from the
-      // recorded core path (its tail must match this core's path relative to the
-      // current project root — '.claude', '.cohorte/<rt>') and re-root anything under
-      // it onto the current projectRoot. Global cores sit outside the project and are
-      // machine-local by definition — their absolute paths pass through untouched.
-      const rel = path.relative(projectRoot, dir);
-      let recordedRoot = null;
-      if (p.core && rel && !rel.startsWith('..') && !path.isAbsolute(rel)
-          && (p.core === rel || p.core.endsWith(path.sep + rel))) {
-        recordedRoot = p.core.slice(0, p.core.length - rel.length - 1) || null;
-      }
-      const abs = (v, fallback) => {
-        const raw = v || fallback;
-        if (!raw) return null;
-        if (!path.isAbsolute(raw)) return path.join(projectRoot, raw);
-        if (recordedRoot && recordedRoot !== projectRoot
-            && (raw === recordedRoot || raw.startsWith(recordedRoot + path.sep))) {
-          return path.join(projectRoot, raw.slice(recordedRoot.length + 1) || '.');
-        }
-        return raw;
-      };
-      found.push({
-        id,
-        label: rec.label || id,
-        scope: rec.scope || scope,
-        core: dir,
-        agents: abs(p.agents, path.join(dir, 'agents')),
-        commands: abs(p.commands, path.join(dir, 'commands')),
-        state: abs(null, p.state || stateDirFor(id)),
-        // Pre-2.2.0 cores carry no registry, so nothing records where the hook is registered.
-        // Claude's is `<core>/settings.json` and always has been — without this fallback a
-        // legacy install reports its perfectly good registration as missing.
-        hooksConfig: (rec.paths && rec.paths.hooks_config)
-          ? abs(rec.paths.hooks_config)
-          : (id === 'claude' ? path.join(dir, 'settings.json') : null),
-        capabilities: rec.capabilities || {
-          subagents: true, hooks: id === 'claude', workflows: id === 'claude',
-        },
-        legacy: !registry,
-      });
-    }
-  }
-  return found;
-}
-
-/**
- * The layout the project-level checks should use. Claude first when present — it is the
- * reference implementation and the layout every pre-2.2.0 repo has — else whatever is
- * installed. Null when nothing is.
- */
-function primary(all) {
-  if (!all.length) return null;
-  return all.find((l) => l.id === 'claude') || all[0];
-}
-
-// The state dirs actually in play. A repo driven from Claude AND Cursor has both `.claude`
-// and `.cohorte`; a check that looked at only one would miss a stamp or a metrics file.
-function stateDirs(all, projectRoot) {
-  const dirs = [];
-  for (const l of all) if (!dirs.includes(l.state)) dirs.push(l.state);
-  if (!dirs.length) dirs.push(path.join(projectRoot, '.claude'));
-  return dirs;
-}
-
-module.exports = { layouts, primary, stateDirs, stateDirFor };

package/lib/versions.js

@@ -1,149 +0,0 @@
-'use strict';
-// Freshness data: which core is installed where, and how it compares to npm latest.
-// Dependency-free — reads VERSION files + the committed pointer, fetches the npm registry.
-
-const fs = require('fs');
-const path = require('path');
-const { spawnSync } = require('child_process');
-const { layouts } = require('./runtime.js');
-
-function readTrimmed(file) {
-  try { return fs.readFileSync(file, 'utf8').trim(); } catch { return null; }
-}
-
-function readJson(file) {
-  try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; }
-}
-
-// Installed core in a given root (global ~/.claude or a repo's bundled .claude).
-function coreAt(claudeDir) {
-  const version = readTrimmed(path.join(claudeDir, 'pipeline', 'VERSION'));
-  return { present: version != null, version, dir: claudeDir };
-}
-
-// The committed per-repo pointer (bundled mode); names the mode + core_version.
-function pointerAt(projectRoot) {
-  const ptr = readJson(path.join(projectRoot, '.claude', 'pipeline.json'));
-  if (!ptr || typeof ptr !== 'object') return { present: false };
-  return { present: true, mode: ptr.mode || null, core_version: ptr.core_version || null };
-}
-
-// 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 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 a batch of probes never finished.
-const FAIL_CACHE_MS = 60 * 1000;
-
-async function fetchRegistry(timeoutMs = 5000) {
-  const ctrl = new AbortController();
-  const t = setTimeout(() => ctrl.abort(), timeoutMs);
-  try {
-    const res = await fetch('https://registry.npmjs.org/cohorte/latest', {
-      signal: ctrl.signal,
-      headers: { accept: 'application/vnd.npm.install-v1+json' },
-    });
-    if (!res.ok) return null;
-    const body = await res.json();
-    return typeof body.version === 'string' ? body.version : null;
-  } catch {
-    return null;
-  } finally {
-    clearTimeout(t);
-  }
-}
-
-// Fallback only — spawnSync blocks the single-threaded server for up to its
-// timeout, so it must stay behind latestNpm()'s cache + in-flight dedupe (at most
-// one call a minute, and only when the registry fetch already failed).
-function npmView() {
-  try {
-    // One static string on Windows (npm is npm.cmd — needs a shell; the
-    // shell+args-array combination is DEP0190-deprecated). Nothing dynamic.
-    const r = process.platform === 'win32'
-      ? spawnSync('npm view cohorte version', { encoding: 'utf8', timeout: 8000, shell: true })
-      : spawnSync('npm', ['view', 'cohorte', 'version'], { encoding: 'utf8', timeout: 8000 });
-    if (r.status === 0 && r.stdout) {
-      const v = r.stdout.trim();
-      return /^\d+\.\d+\.\d+/.test(v) ? v : null;
-    }
-  } catch { /* npm absent or slow */ }
-  return null;
-}
-
-let _inflight = null;
-// `opts` bounds what a CALLER is willing to pay for the answer. The CLI's staleness
-// notice runs at the tail of an install, where the default 5s fetch + 8s `npm view`
-// fallback would make an OFFLINE install appear to hang for 13 seconds after it had
-// already succeeded — so it asks for a short fetch and no fallback. The cache is
-// shared across callers either way: a cheap lookup still serves an expensive one.
-async function latestNpm({ timeoutMs = 5000, fallback = true } = {}) {
-  const age = Date.now() - _cache.at;
-  if (_cache.at && age < (_cache.value ? CACHE_MS : FAIL_CACHE_MS)) return _cache.value;
-  // /api/fleet resolves N projects concurrently — without this, N lookups race and
-  // each pays the full timeout instead of sharing one.
-  if (_inflight) return _inflight;
-  _inflight = (async () => {
-    try {
-      const v = (await fetchRegistry(timeoutMs)) || (fallback ? npmView() : null);
-      _cache = { value: v || null, at: Date.now() };
-      return v || null;
-    } finally {
-      _inflight = null;
-    }
-  })();
-  return _inflight;
-}
-
-// Naive semver compare — returns -1|0|1 (a<b|a==b|a>b). Ignores pre-release tags.
-function cmpSemver(a, b) {
-  if (!a || !b) return null;
-  const pa = a.split('.').map(n => parseInt(n, 10) || 0);
-  const pb = b.split('.').map(n => parseInt(n, 10) || 0);
-  for (let i = 0; i < 3; i++) {
-    if ((pa[i] || 0) < (pb[i] || 0)) return -1;
-    if ((pa[i] || 0) > (pb[i] || 0)) return 1;
-  }
-  return 0;
-}
-
-async function versions({ projectRoot, globalDir, cliVersion }) {
-  const global = coreAt(globalDir);
-  let bundled = coreAt(path.join(projectRoot, '.claude'));
-  const pointer = pointerAt(projectRoot);
-  const latest = await latestNpm();
-
-  // A non-Claude runtime keeps its core in `.cohorte/<id>/`, not `.claude/`. Probing only the
-  // Claude path reported a perfectly installed Cursor/Codex/Gemini/OpenCode repo as having no
-  // core at all — and every downstream check keys off `installMode`, so one wrong probe turned
-  // the whole report red.
-  if (!bundled.present) {
-    const projectCore = layouts({ projectRoot, globalDir })
-      .find(l => l.scope === 'project' && l.core.startsWith(projectRoot));
-    if (projectCore) bundled = coreAt(projectCore.core);
-  }
-
-  // The core that actually serves this project: bundled wins if present, else global.
-  const effective = bundled.present ? bundled : global.present ? global : null;
-  const installedVersion = effective ? effective.version : null;
-  const behind = cmpSemver(installedVersion, latest);
-
-  return {
-    cli: cliVersion,
-    latest,
-    global,
-    bundled,
-    pointer,
-    installMode: bundled.present ? 'bundled' : global.present ? 'global' : 'none',
-    installedVersion,
-    // -1 behind, 0 up-to-date, 1 ahead of registry (dev), null unknown
-    freshness: behind,
-    // freshness of the GLOBAL core specifically (for the fleet banner, independent of project mode)
-    globalFreshness: global.present ? cmpSemver(global.version, latest) : null,
-  };
-}
-
-module.exports = { versions, latestNpm, cmpSemver };

package/lib/yaml.js

@@ -1,129 +0,0 @@
-'use strict';
-// Minimal block-YAML parser — just enough for the `yaml pipeline-profile` block in PIPELINE.md.
-// Deliberately dependency-free (keeps the published package zero-dep). Handles:
-//   key: value · nested maps (indent) · block sequences (- item / - key: val) ·
-//   flow arrays [a, b] · flow maps { a: 1 } · quoted scalars · #-comments · bool/int coercion.
-// NOT a general YAML implementation — anchors, multi-line scalars, etc. are out of scope.
-
-function stripComment(line) {
-  let q = null;
-  for (let i = 0; i < line.length; i++) {
-    const c = line[i];
-    if (q) { if (c === q) q = null; continue; }
-    if (c === '"' || c === "'") { q = c; continue; }
-    // A '#' starts a comment only at line start or after whitespace (YAML rule).
-    if (c === '#' && (i === 0 || /\s/.test(line[i - 1]))) return line.slice(0, i);
-  }
-  return line;
-}
-
-function splitTopLevel(s) {
-  const out = [];
-  let depth = 0, q = null, cur = '';
-  for (let i = 0; i < s.length; i++) {
-    const c = s[i];
-    if (q) { cur += c; if (c === q) q = null; continue; }
-    if (c === '"' || c === "'") { q = c; cur += c; continue; }
-    if (c === '[' || c === '{') { depth++; cur += c; continue; }
-    if (c === ']' || c === '}') { depth--; cur += c; continue; }
-    if (c === ',' && depth === 0) { out.push(cur); cur = ''; continue; }
-    cur += c;
-  }
-  if (cur.trim() !== '') out.push(cur);
-  return out;
-}
-
-function scalar(raw) {
-  const v = raw.trim();
-  if (v === '') return null;
-  if (v[0] === '[') {
-    const inner = v.slice(1, v.lastIndexOf(']'));
-    return inner.trim() === '' ? [] : splitTopLevel(inner).map(scalar);
-  }
-  if (v[0] === '{') {
-    const inner = v.slice(1, v.lastIndexOf('}'));
-    const obj = {};
-    if (inner.trim() !== '') {
-      for (const pair of splitTopLevel(inner)) {
-        const idx = pair.indexOf(':');
-        if (idx === -1) continue;
-        obj[pair.slice(0, idx).trim()] = scalar(pair.slice(idx + 1));
-      }
-    }
-    return obj;
-  }
-  if ((v[0] === '"' && v[v.length - 1] === '"') || (v[0] === "'" && v[v.length - 1] === "'")) {
-    return v.slice(1, -1);
-  }
-  if (v === 'true') return true;
-  if (v === 'false') return false;
-  if (v === 'null' || v === '~') return null;
-  if (/^-?\d+$/.test(v)) return parseInt(v, 10);
-  return v;
-}
-
-// Split "key: rest" on the FIRST colon. A colon inside the value (a URL, a
-// chained shell command) is therefore kept in `rest`, which is what we want;
-// callers are responsible for not feeding this a flow scalar (`[a, b]` /
-// `{a: 1}`) — the block parser checks the first character before calling.
-function keyValue(text) {
-  const idx = text.indexOf(':');
-  if (idx === -1) return null;
-  return { key: text.slice(0, idx).trim(), rest: text.slice(idx + 1).trim() };
-}
-
-function parse(text) {
-  const lines = [];
-  for (const raw of text.split('\n')) {
-    const stripped = stripComment(raw).replace(/\s+$/, '');
-    if (stripped.trim() === '') continue;
-    lines.push({ indent: stripped.match(/^ */)[0].length, text: stripped.trim() });
-  }
-
-  let pos = 0;
-  function block(indent) {
-    const isSeq = lines[pos].text.startsWith('- ');
-    const result = isSeq ? [] : {};
-    while (pos < lines.length && lines[pos].indent >= indent) {
-      if (lines[pos].indent > indent) { pos++; continue; } // defensive: skip stray deeper line
-      const line = lines[pos];
-
-      if (line.text.startsWith('- ')) {
-        const remainder = line.text.slice(2).trim();
-        const kv = keyValue(remainder);
-        // A dash item that is `key: …` (not a flow scalar) opens a nested map.
-        if (kv && remainder[0] !== '[' && remainder[0] !== '{' && /^[\w.-]+$/.test(kv.key)) {
-          lines[pos] = { indent: indent + 2, text: remainder }; // realign so the item's keys share one indent
-          result.push(block(indent + 2));
-        } else {
-          result.push(scalar(remainder));
-          pos++;
-        }
-        continue;
-      }
-
-      const kv = keyValue(line.text);
-      if (!kv) { pos++; continue; }
-      if (kv.rest === '') {
-        pos++;
-        if (pos < lines.length && lines[pos].indent > indent) result[kv.key] = block(lines[pos].indent);
-        else result[kv.key] = null;
-      } else {
-        result[kv.key] = scalar(kv.rest);
-        pos++;
-      }
-    }
-    return result;
-  }
-
-  return lines.length ? block(lines[0].indent) : {};
-}
-
-// Extract + parse the ```yaml pipeline-profile fenced block from a PIPELINE.md string.
-function parseProfileBlock(md) {
-  const m = md.match(/```yaml pipeline-profile\r?\n([\s\S]*?)\r?\n```/);
-  if (!m) return null;
-  return parse(m[1]);
-}
-
-module.exports = { parse, parseProfileBlock };

package/profile/PIPELINE.template.md

@@ -1,251 +0,0 @@
-# PIPELINE.md — <PROJECT_NAME> profile
-
-> **Generated by `/cohorte-init-pipeline`.** This is the project profile: the single place the
-> portable multi-agent pipeline reads for everything stack-specific. The pipeline core
-> in the pipeline core is generic and references THIS file by section — keep project facts
-> here, never hardcoded into agent prompts. Kept current by `/cohorte-update-pipeline` (reconcile:
-> new fields are topped up, your values never overwritten). Rendered agent files are
-> regenerated from this profile on every reconcile — customize agents through §Conventions
-> here, never by editing the agent files. Free-form notes belong in `CLAUDE.md`.
->
-> **Machine block first, prose after.** The fenced `yaml pipeline-profile` block below is
-> the deterministic contract (flags, surfaces, commands) — commands parse it and branch on
-> it. The prose sections carry conventions agents read.
-
-```yaml pipeline-profile
-# ── identity ────────────────────────────────────────────────────────────────
-name: <PROJECT_NAME>
-one_liner: <one sentence: what this product is>
-ui_language: <English | French | …>          # language of ALL user-facing copy
-package_manager: <pnpm | npm | yarn | bun | pip | cargo | go>
-
-# ── vcs ─────────────────────────────────────────────────────────────────────
-vcs:
-  host: <github | gitlab | none>
-  remote: <owner/repo>                        # e.g. acme/webapp
-  default_branch: <main>
-  feature_branch_prefix: feature/            # branch = <prefix><feature_id>
-  patch_branch_prefix: fix/                  # same, for /cohorte-patch specs (kind: patch)
-
-# ── repo shape ──────────────────────────────────────────────────────────────
-repo:
-  layout: <monorepo | single>
-  workspace_tool: <turborepo | nx | none>
-
-# ── code retrieval (semantic navigation — cuts agent read time) ─────────────
-# Agents prefer symbol/graph MCP queries over grep-and-read when a provider is
-# wired. serena = live LSP symbol navigation (default, no index to maintain);
-# graphify = persistent tree-sitter knowledge graph over code + docs (needs an
-# index step + rescans); none = agents fall back to Grep/Glob/Read.
-# Registered by /cohorte-init-pipeline as a project-scope MCP server (committed .mcp.json).
-retrieval:
-  provider: serena                            # serena | graphify | none
-
-# ── surfaces ────────────────────────────────────────────────────────────────
-# One entry per independently-implemented code area. /cohorte-build dispatches ONE
-# implementer agent per surface, in parallel. Each surface is rendered by
-# /cohorte-init-pipeline into its own agent file (agent field) with the tools listed.
-# This list GROWS automatically: /cohorte-build §1.5 adds a surface (and renders its
-# agent) when a spec touches a tree no surface owns, or splits a bottleneck
-# surface into specialized sub-surfaces. Keep one owner per tree; shared code
-# (routing/state/DS) is its own single-owner surface. See SCHEMA.md §Specialization.
-surfaces:
-  - key: backend                              # short id, used as agent name + scope
-    path: apps/api                            # the ONLY tree this surface's agent may touch
-    label: backend (AdonisJS)
-    agent: backend                            # rendered as backend.md in this runtime's agents dir
-    tools: [Read, Write, Edit, Bash, Grep, Glob, mcp__serena]   # mcp__<provider> mirrors retrieval.provider
-    model: sonnet                             # frontmatter model tier: sonnet | haiku | inherit
-                                              #   sonnet = default (applies the frozen contract — cheap
-                                              #   vs the Opus lead); haiku = purely mechanical scaffolding;
-                                              #   inherit = only for surfaces with real design decisions
-    test_cmd: pnpm --filter api test
-    # Bridled variants — what agents actually RUN (dot reporter / failures-only /
-    # --quiet), so a green run costs lines, not pages. "" ⇒ callers fall back to
-    # `<cmd> 2>&1 | tail -40`. /cohorte-init-pipeline asks for these; never store a bare
-    # `pnpm test` as the thing agents execute.
-    test_quiet_cmd: pnpm --filter api test --reporter=dot
-    lint_cmd: pnpm --filter api lint
-    lint_quiet_cmd: pnpm --filter api lint --quiet
-    format_cmd: pnpm --filter api format
-    typecheck_cmd: pnpm --filter api exec tsc --noEmit
-    build_cmd: ""
-    uses_design: false
-  - key: frontend
-    path: apps/web
-    label: frontend (React/TanStack)
-    agent: frontend
-    tools: [Read, Write, Edit, Bash, Grep, Glob, DesignSync, mcp__serena]
-    model: sonnet                             # default even for design surfaces — designs + contract are
-                                              #   frozen inputs the agent applies; `inherit` (bills at the
-                                              #   lead's tier, often Opus) ONLY if this surface must make
-                                              #   novel design decisions
-    test_cmd: pnpm --filter web test
-    test_quiet_cmd: pnpm --filter web test --reporter=dot
-    lint_cmd: pnpm --filter web lint
-    lint_quiet_cmd: pnpm --filter web lint --quiet
-    format_cmd: pnpm --filter web format
-    typecheck_cmd: pnpm check-types
-    build_cmd: pnpm --filter web build
-    uses_design: true
-
-# ── contract (the only cross-surface sync channel) ──────────────────────────
-contract:
-  enabled: <true | false>                     # false ⇒ no shared contract; skip §2 of /cohorte-build
-  mechanism: <shared-types-zod | openapi | protobuf | json-schema | none>
-  path: packages/shared-types/src             # where <feature_id>.<ext> is authored
-  ext: ts
-  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
-  dev: pnpm dev
-  lint: pnpm lint
-  lint_quiet: pnpm lint --quiet              # bridled variant (see surfaces[].*_quiet_cmd)
-  format: pnpm format
-  typecheck: pnpm check-types
-  test: pnpm test
-  test_quiet: pnpm test --reporter=dot       # bridled variant — what the /cohorte-review preflight runs
-  # migration commands — omit / leave "" if the project has no DB migrations
-  migrate: "cd apps/api && node ace migration:run"
-  make_migration: "cd apps/api && node ace make:migration"
-
-# ── rbac (optional) ─────────────────────────────────────────────────────────
-rbac:
-  enabled: <true | false>
-  hierarchy: [super-admin, admin, editor, member]   # highest → lowest, or []
-  note: "the platform must serve EVERY role, not just admins"
-
-# ── design system (optional) ────────────────────────────────────────────────
-design:
-  enabled: <true | false>                     # false ⇒ /cohorte-align-ds + design gates are no-ops
-  provider: <claude-design | figma | none>
-  design_system_project: <uuid-or-id>         # the UI-kit source of truth
-  design_project: none                        # legacy fallback for bare-filename design_files only; keep `none` — new specs use full links that carry their own project, so nothing here goes stale on a DS rebuild
-  snapshot_dir: apps/web/design-reference     # committed DS snapshot for /cohorte-align-ds diff
-  direction: design-to-code                   # NEVER push code→design for a curated DS
-  ui_kit_path: apps/web/src/components/ui
-  tokens_path: apps/web/src/index.css
-
-# ── isolation / parallelism (optional) ──────────────────────────────────────
-isolation:
-  enabled: <true | false>                     # false ⇒ features run in the main checkout
-  unit: git-worktree
-  db_per_worktree: <true | false>
-  db_name_pattern: "<name>_<id>"              # e.g. myapp_<id>
-  port_base: { api: 3333, web: 5173 }         # each worktree gets base+slot
-  compose_file: docker-compose.yml
-  registry: .worktrees/slots.tsv
-
-# ── gate (drives the pipeline gate hook + permissions) ─────────────────────
-# Confirm-first or hard-deny on dangerous Bash, inspecting the FULL command
-# string (so chained `cd x && …` forms are caught).
-gate:
-  # Three tiers. `deny` = always hard-blocked. `ask` = always confirm (branch-independent risk).
-  # `ask_on_default_branch` = confirm ONLY when the checked-out branch is `default_branch`; on
-  # feature branches these run freely. gate.py resolves the branch at run time (git rev-parse);
-  # unknown branch (no repo / detached) ⇒ gated, to stay safe. Keep git + docker here so agents
-  # move fast on feature branches but main stays protected.
-  default_branch: main                        # the protected branch (mirror vcs.default_branch)
-  deny:                                       # never allowed, on any branch
-    - "node ace migration:fresh"
-    - "node ace migration:reset"
-    - "node ace migration:rollback"
-    - "node ace db:wipe"
-  ask:                                         # always confirm, on any branch
-    - "node ace migration:run"
-    - "node ace db:"
-    - "psql"
-  ask_on_default_branch:                        # free on feature branches, confirm on default_branch
-    - "git commit"
-    - "git push"
-    - "git merge"
-    - "git rebase"
-    - "git reset"
-    - "docker compose"
-  # Phase gate: review dispatches require a fresh `preflight.ok` stamp,
-  # written by pipeline/scripts/preflight.sh when typecheck+lint+tests are green —
-  # gate.py "ask"s the dispatch when the stamp is missing, stale, or the code changed since.
-  # The stamp is local: keep `preflight.ok` gitignored, never committed.
-  preflight:
-    enabled: true
-    agents: [review]                          # subagent_types the stamp gates
-    max_age_minutes: 30
-
-```
-
-> **Note.** The **kanban** board link is **user-scoped** — NOT configured here. Its facts live in the
-> consolidated user config (`~/.claude/cohorte.config.yaml`, or `~/.cohorte/cohorte.config.yaml` on
-> a non-Claude runtime), read at runtime (the kanban board is keyed by this
-> profile's `name`). This project profile only governs the dev pipeline (`/cohorte-brainstorm…/cohorte-ship`).
-
----
-
-## Conventions
-
-> Read by the implementer + review agents. Keep these terse and rule-shaped; the machine
-> block above holds the paths/commands they enforce against.
-
-### Shared
-
-- User-facing copy (API messages, UI text) in **<ui_language>**.
-- <e.g. Zod v4 syntax `z.email()`/`z.uuid()`; ESM `.js` import extensions — project-specific>
-
-### Surface: `backend` (`apps/api`)
-
-- <one-action controllers · validator on every write · standardized response envelope · base model / UUID PK · `#`-alias imports · additive-only migrations · …>
-
-### Surface: `frontend` (`apps/web`)
-
-- <file-based routes with loaders/guards · domain `lib/api` modules over the shared client · design-system primitives, `cn()`+CVA · **mobile-first, fully responsive** · consume contract types, never redefine · …>
-
-### Testing — strict TDD (red → green → refactor)
-
-- <backend test runner + what a contract test must cover (status, validation, auth, payload) · DB isolation per test>
-- <frontend test runner + what to cover (hooks, api modules, component behavior); note layout is not unit-testable>
-
----
-
-## Design brief note (feeds `/cohorte-spec` §8 and Claude Design)
-
-- <design system name + primitives to use · mobile-first · copy language · brand/theming constraints>
-- A feature lists its design pages in the spec front-matter `design_files` as **full links** of the form
-  `https://claude.ai/design/p/<projectId>?file=<file>` — each carries its own project (`/p/<projectId>`)
-  and page (`?file=`), so an agent extracts both and reads it via `DesignSync get_file(<projectId>,
-  <file>)`. Paste the link at `/cohorte-build`'s design gate. No stored project id ⇒ a design-system rebuild
-  (new project) just means pasting the new links. (Bare file names are legacy, resolved in `design_project`.)
-
----
-
-## Personas for `/cohorte-brainstorm` (optional — the panel)
-
-<Panel members with a job AND a personality who challenge the idea from their angle and
-disagree with each other. Include a role-coverage guard if `rbac.enabled`. Example:>
-
-- **PM** (pragmatic, scope-cutting) — real value? what do we drop?
-- **Skeptical senior engineer** (blunt) — feasibility, edge cases, tech debt.
-- **UX/product designer** — mobile-first flows, accessibility, empty/error states.
-- **Security & RBAC** (paranoid) — permission leaks, cross-tenant exposure, least privilege.
-- <one persona per RBAC role so the feature serves every role, not just admins>