cohorte 2.0.2 → 2.2.0

package/core/adapter/render.js

@@ -0,0 +1,389 @@
+#!/usr/bin/env node
+// cohorte — runtime adapter.
+//
+// The core prompts (core/commands/*.md, core/agents/*.md) are the SINGLE source of
+// truth and are written runtime-neutral. This module transpiles them into whatever
+// the target coding agent actually reads:
+//
+//                 commands                        agents                  gate hook
+//   claude    .claude/commands/<n>.md         md, $ARGUMENTS      md      PreToolUse (deny+ask)
+//   codex     .agents/skills/<n>/SKILL.md     md, no substitution toml    PreToolUse (deny only)
+//   cursor    .cursor/commands/<n>.md         md, no substitution md      beforeShellExecution
+//   gemini    .gemini/commands/<n>.toml       toml, {{args}}      md      BeforeTool (deny only)
+//   opencode  .opencode/commands/<n>.md       md, $ARGUMENTS      md      none — advisory --check
+//
+// Three transforms, in order:
+//
+//   1. capability conditionals — `<!-- cohorte:if hooks -->…<!-- cohorte:else -->…
+//      <!-- cohorte:endif -->` keeps exactly one branch, so one file can state both "the gate
+//      fires whether or not you cooperate" and "you must call the gate yourself".
+//   2. runtime preamble — one block resolving `<core>`, `<agents>`, the dispatch verb and
+//      the gate mechanism, so the prose below never hardcodes a runtime's layout.
+//   3. surface encoding — frontmatter filtered to the keys that runtime understands (an
+//      unknown key is prose the model reads as an instruction, so dropping is not cosmetic),
+//      arg placeholder swapped, and the whole thing re-emitted as md, toml or a skill dir.
+//
+// Subagents are NOT one of the conditionals: they are a precondition (see assertSupported).
+//
+// Claude output is byte-identical to the pre-adapter core when a file has no conditionals:
+// that is the regression test (scripts/test-adapter.mjs).
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const RUNTIME_DIR = path.join(__dirname, '..', 'runtimes');
+
+// --- registry ----------------------------------------------------------------
+
+function listRuntimes() {
+  return fs.readdirSync(RUNTIME_DIR)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => f.slice(0, -5))
+    .sort();
+}
+
+function loadRuntime(id) {
+  const file = path.join(RUNTIME_DIR, `${id}.json`);
+  if (!fs.existsSync(file)) {
+    throw new Error(`unknown runtime "${id}" (known: ${listRuntimes().join(', ')})`);
+  }
+  const rt = JSON.parse(fs.readFileSync(file, 'utf8'));
+  assertSupported(rt);
+  return rt;
+}
+
+// Subagents are a HARD requirement, not a capability to branch on. The pipeline's premise is
+// that each surface is built by someone who can only see the frozen contract; without real
+// subagents the lead does every surface in one context and that isolation is simply gone.
+// A sequential-persona fallback existed briefly and was removed: it asked the lead to simulate
+// the boundary by discipline, which is not the same guarantee, and no supported runtime ever
+// took that branch. Refuse loudly rather than render a pipeline whose central promise is absent.
+function assertSupported(rt) {
+  if (rt.capabilities && rt.capabilities.subagents === false) {
+    throw new Error(`runtime "${rt.id}" declares no subagents — cohorte requires them `
+      + '(see docs/reference/runtimes.md §Requirements)');
+  }
+  return rt;
+}
+
+function expandHome(p) {
+  if (!p) return p;
+  return p.startsWith('~/') ? path.join(os.homedir(), p.slice(2)) : p;
+}
+
+// Which runtimes are actually installed on this machine. Detection is by config
+// directory, not by binary on PATH: Cursor ships no CLI, and a runtime the human
+// has configured but not opened this shell for is still a legitimate target.
+function detectRuntimes() {
+  return listRuntimes().filter((id) => {
+    const rt = loadRuntime(id);
+    return (rt.detect || []).some((d) => fs.existsSync(expandHome(d)));
+  });
+}
+
+// Absolute destinations for one (runtime, scope) pair. `projectRoot` anchors every
+// relative path; `~`-rooted ones ignore it. A scope entry may pin an individual
+// surface to another scope (Codex reads prompts ONLY from ~/.codex, even when the
+// neutral core is bundled in the repo) via `<key>_scope`.
+function resolvePaths(runtime, scope, projectRoot, { overrides } = {}) {
+  const spec = runtime.scopes[scope];
+  if (!spec) throw new Error(`runtime ${runtime.id} has no "${scope}" scope`);
+  // `overrides` re-roots a declared prefix — the one caller is CLAUDE_CONFIG_DIR, which moves
+  // Claude Code's whole `~/.claude` tree elsewhere (a desktop host points it at
+  // `~/Library/Application Support/…`). Ignoring it split the install in half: the core was
+  // written to `~/.claude` while the hook was registered in the overridden dir, so a scratch
+  // install silently wrote into the user's real global core.
+  const reroot = (p) => {
+    for (const [from, to] of Object.entries(overrides || {})) {
+      if (p === from) return to;
+      if (p.startsWith(from + '/')) return to + p.slice(from.length);
+    }
+    return p;
+  };
+  const abs = (p) => {
+    if (!p) return null;
+    const e = expandHome(reroot(p));
+    return path.isAbsolute(e) ? e : path.join(projectRoot, e);
+  };
+  const out = { scope, effective: {} };
+  for (const key of ['root', 'core', 'commands', 'agents', 'hooks', 'hooks_config',
+                     'workflows', 'settings']) {
+    out[key] = abs(spec[key]);
+    out.effective[key] = spec[`${key}_scope`] || scope;
+  }
+  return out;
+}
+
+// --- 1. capability conditionals ----------------------------------------------
+
+const IF = /^\s*<!--\s*cohorte:if\s+([^>]+?)\s*-->\s*$/;
+const ELSE = /^\s*<!--\s*cohorte:else\s*-->\s*$/;
+const ENDIF = /^\s*<!--\s*cohorte:endif\s*-->\s*$/;
+
+// A condition is a space-separated OR of terms; a term is `cap`, `!cap`, `runtime:<id>`
+// or `!runtime:<id>`. OR (not AND) because every real use is "this family of runtimes".
+function testCondition(expr, runtime) {
+  return expr.split(/\s+/).filter(Boolean).some((term) => {
+    const neg = term.startsWith('!');
+    const name = neg ? term.slice(1) : term;
+    let value;
+    if (name.startsWith('runtime:')) value = runtime.id === name.slice(8);
+    else if (name in (runtime.capabilities || {})) value = !!runtime.capabilities[name];
+    else throw new Error(`unknown cohorte:if term "${name}"`);
+    return neg ? !value : value;
+  });
+}
+
+function applyConditionals(text, runtime) {
+  const lines = text.split('\n');
+  const out = [];
+  // Each frame: {keep} — whether the branch currently being read survives. Nesting is
+  // supported so a hooks-branch can carry a subagents-branch inside it.
+  const stack = [];
+  const emitting = () => stack.every((f) => f.keep);
+  for (const line of lines) {
+    let m;
+    if ((m = line.match(IF))) {
+      const taken = testCondition(m[1], runtime);
+      stack.push({ taken, keep: taken, seenElse: false });
+      continue;
+    }
+    if (ELSE.test(line)) {
+      const frame = stack[stack.length - 1];
+      if (!frame) throw new Error('cohorte:else without a matching cohorte:if');
+      if (frame.seenElse) throw new Error('two cohorte:else in one cohorte:if');
+      frame.seenElse = true;
+      frame.keep = !frame.taken;
+      continue;
+    }
+    if (ENDIF.test(line)) {
+      if (!stack.pop()) throw new Error('cohorte:endif without a matching cohorte:if');
+      continue;
+    }
+    if (emitting()) out.push(line);
+  }
+  if (stack.length) throw new Error('unclosed cohorte:if');
+  return out.join('\n');
+}
+
+// --- 2. runtime preamble ------------------------------------------------------
+
+// Path as the human/model should see it: `~/…` reads better than an expanded homedir,
+// and a project-relative path must stay relative (the agent's cwd is the repo).
+function displayPath(p, projectRoot) {
+  if (!p) return null;
+  const home = os.homedir();
+  if (p.startsWith(home + path.sep)) return '~/' + path.relative(home, p).split(path.sep).join('/');
+  if (p.startsWith(projectRoot + path.sep)) return path.relative(projectRoot, p).split(path.sep).join('/');
+  return p;
+}
+
+// The per-project directory holding everything the pipeline GENERATES for this repo
+// (gate-config.json, preflight.ok, pipeline-metrics.jsonl, pipeline.json). Distinct from
+// `<core>`: the core can be global while this is always in the repo, next to the code it
+// describes. `.claude` on a Claude install — unchanged, so existing repos keep working.
+//
+// Deliberately SHARED across non-Claude runtimes (`.cohorte`), while each of their cores is
+// its own subdirectory (`.cohorte/<id>`). The state describes the PROJECT — one gate config,
+// one preflight stamp, one metrics log — and duplicating it per runtime would let a repo
+// driven from two agents disagree with itself about what is gated and what is verified.
+// The core, by contrast, is rendered per runtime and cannot be shared: the same template
+// resolves differently depending on whether that agent has subagents or hooks.
+function stateDir(runtime) {
+  return runtime.id === 'claude' ? '.claude' : '.cohorte';
+}
+
+// The user-level config (kanban boards, shared vault, telemetry consent). One file per
+// human, not per project or per runtime; the shipped scripts probe the same two paths.
+function configPath(runtime) {
+  return runtime.id === 'claude' ? '~/.claude/cohorte.config.yaml' : '~/.cohorte/cohorte.config.yaml';
+}
+
+function preamble(runtime, paths, projectRoot, { kind = 'command' } = {}) {
+  const caps = runtime.capabilities || {};
+  const core = displayPath(paths.core, projectRoot);
+  const agentsDir = paths.agents ? displayPath(paths.agents, projectRoot) : `${core}/agents`;
+  const L = [];
+  L.push(`> **Runtime: ${runtime.label}.** Generated by the cohorte adapter — do not edit this file;`);
+  L.push(`> edit \`core/${kind === 'agent' ? 'agents' : 'commands'}/\` in the cohorte source and re-install.`);
+  L.push('>');
+  L.push(`> - \`<core>\` = \`${core}\` — the pipeline's shared assets (\`pipeline/scripts/\`, \`pipeline/SCHEMA.md\`, \`templates/\`). Every \`<core>/…\` path below resolves there, and nowhere else.`);
+  L.push(`> - \`<state>\` = \`${stateDir(runtime)}/\` in **this repo** — what the pipeline generates for this project (\`gate-config.json\`, \`preflight.ok\`, \`pipeline-metrics.jsonl\`, \`pipeline.json\`). Always project-relative, even when \`<core>\` is global.`);
+  L.push(`> - \`<memory>\` = \`${runtime.memory}\` — this runtime's project-instructions file at the repo root, loaded into every session here. Where the doctrine says to reference or extend it, that is the file.`);
+  L.push(`> - \`<config>\` = \`${configPath(runtime)}\` — your user-level config (kanban boards, shared vault, telemetry consent). One per human, never committed.`);
+
+  L.push(`> - \`<agents>\` = \`${agentsDir}\` — real subagents. Dispatch: ${runtime.agent.dispatch}.`);
+
+  if (caps.hooks) {
+    const cfg = displayPath(paths.hooks_config, projectRoot);
+    const ask = runtime.hook.supports_ask
+      ? 'It can deny outright or ask you to confirm.'
+      : 'This runtime has **no confirmation tier**, so a command that would merely be queried elsewhere is **denied** here — re-run it yourself if you meant it.';
+    L.push(`> - **Gate** — \`<core>/hooks/gate.py\` is registered as a blocking \`${runtime.hook.event}\` hook in \`${cfg}\`, reading \`<state>/gate-config.json\`. It fires whether or not you cooperate. ${ask}`);
+  }
+
+  if (!caps.hooks) {
+    L.push('> - **Gate** — this runtime has no blocking hook, so the gate is not automatic. Before any command listed in the profile\'s `gate` block, and before every phase dispatch, run `<core>/hooks/gate.py --check <command>` yourself and obey its verdict (`deny` ⇒ stop, `ask` ⇒ get the human\'s explicit go-ahead). Skipping this is the one deviation that silently removes a safety property.');
+  }
+
+  if (!caps.workflows) {
+    L.push('> - **Workflows** — unavailable on this runtime. The conversational path below is the only path; ignore any mention of a workflow variant.');
+  }
+
+  if (!runtime.command.args) {
+    L.push(`> - \`$ARGUMENTS\` — this runtime does not substitute placeholders. It means ${runtime.command.args_note || 'the text typed after the command name'}; expand it yourself everywhere it appears below.`);
+  }
+
+  return L.join('\n') + '\n';
+}
+
+// --- 3. surface encoding ------------------------------------------------------
+
+function parseFrontmatter(text) {
+  if (!text.startsWith('---\n')) return { keys: [], body: text };
+  const end = text.indexOf('\n---\n', 3);
+  if (end === -1) return { keys: [], body: text };
+  const block = text.slice(4, end + 1);
+  const body = text.slice(end + 5);
+  const keys = [];
+  for (const line of block.split('\n')) {
+    const m = line.match(/^([A-Za-z][\w-]*):\s?(.*)$/);
+    // Continuation lines (a wrapped value) belong to the previous key.
+    if (!m) {
+      if (line.trim() && keys.length) keys[keys.length - 1][1] += '\n' + line;
+      continue;
+    }
+    keys.push([m[1], m[2]]);
+  }
+  return { keys, body };
+}
+
+function emitFrontmatter(keys) {
+  if (!keys.length) return '';
+  return '---\n' + keys.map(([k, v]) => `${k}: ${v}`).join('\n') + '\n---\n\n';
+}
+
+function substituteArgs(text, runtime) {
+  const token = runtime.command.args;
+  if (!token || token === '$ARGUMENTS') return text;
+  return text.split('$ARGUMENTS').join(token);
+}
+
+// TOML basic-string escaping for the multi-line ''' form Gemini expects. A literal
+// ''' inside a prompt would close the string early, so it is the one sequence broken up.
+function tomlMultiline(s) {
+  return "'''\n" + s.replace(/'''/g, "''\\'") + "\n'''";
+}
+function tomlBasic(s) {
+  return '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, ' ') + '"';
+}
+
+/**
+ * Render one core command for one runtime.
+ * @returns {{filename: string, content: string, dir: 'commands'}}
+ */
+function renderCommand({ source, name, runtime, paths, projectRoot }) {
+  const { keys, body } = parseFrontmatter(source);
+  let out = applyConditionals(body, runtime);
+  out = preamble(runtime, paths, projectRoot) + '\n' + out.replace(/^\n+/, '');
+  out = substituteArgs(out, runtime);
+
+  const kept = keys.filter(([k]) => runtime.command.frontmatter.includes(k));
+  const dropped = keys.filter(([k]) => !runtime.command.frontmatter.includes(k)).map(([k]) => k);
+
+  // A skill is a DIRECTORY — `<name>/SKILL.md` — whose frontmatter must carry `name`, since
+  // that is what the runtime matches on (both for `$<name>` and for implicit selection from
+  // `description`). Command sources have no `name` key, so synthesise it from the filename.
+  if (runtime.command.format === 'skill') {
+    if (!kept.some(([k]) => k === 'name')) kept.unshift(['name', name]);
+    return { filename: `${name}${runtime.command.ext}`, content: emitFrontmatter(kept) + out, dropped };
+  }
+
+  if (runtime.command.format === 'toml') {
+    const desc = (keys.find(([k]) => k === 'description') || [null, ''])[1];
+    const lines = [`# cohorte — generated for ${runtime.label}. Do not edit; edit core/commands/${name}.md.`];
+    if (dropped.length) lines.push(`# frontmatter not supported here, dropped: ${dropped.join(', ')}`);
+    if (desc) lines.push(`description = ${tomlBasic(desc)}`);
+    lines.push(`prompt = ${tomlMultiline(substituteArgs(out, runtime))}`);
+    return { filename: `${name}${runtime.command.ext}`, content: lines.join('\n') + '\n', dropped };
+  }
+
+  const header = emitFrontmatter(kept);
+  return { filename: `${name}${runtime.command.ext}`, content: header + out, dropped };
+}
+
+// Is this agent read-only? Derived from the source's Claude-style `tools:` list rather than
+// declared twice: an agent that was never given Write, Edit or Bash is read-only by intent,
+// and each runtime spells that its own way (`readonly: true`, `sandbox_mode = "read-only"`).
+// Losing it silently would hand the reviewer the ability to fix what it is meant to report.
+function isReadOnly(keys) {
+  const tools = (keys.find(([k]) => k === 'tools') || [])[1];
+  if (!tools) return false;
+  return !/\b(Write|Edit|MultiEdit|Bash|NotebookEdit)\b/.test(tools);
+}
+
+/**
+ * Render one core agent for one runtime.
+ *
+ * Every runtime cohorte targets has real subagents, but they disagree on the file: markdown +
+ * frontmatter for Claude Code, Cursor, Gemini CLI and OpenCode; TOML with the body under
+ * `developer_instructions` for Codex. `format: "persona"` remains for a runtime with no
+ * subagents at all — the file is then read and adopted by the lead in sequence.
+ */
+function renderAgent({ source, name, runtime, paths, projectRoot }) {
+  const { keys, body } = parseFrontmatter(source);
+  const out = preamble(runtime, paths, projectRoot, { kind: 'agent' }) + '\n'
+    + applyConditionals(body, runtime).replace(/^\n+/, '');
+  const spec = runtime.agent;
+  const readonly = isReadOnly(keys);
+
+  if (spec.format === 'toml') {
+    const get = (k) => (keys.find(([kk]) => kk === k) || [null, ''])[1];
+    const lines = [`# cohorte — generated for ${runtime.label}. Do not edit; edit core/agents/${name}.md.`];
+    lines.push(`name = ${tomlBasic(get('name') || name)}`);
+    if (get('description')) lines.push(`description = ${tomlBasic(get('description'))}`);
+    if (spec.frontmatter.includes('model') && get('model')) lines.push(`model = ${tomlBasic(get('model'))}`);
+    if (readonly && spec.readonly_key) {
+      lines.push(`${spec.readonly_key} = ${tomlBasic(spec.readonly_value)}`);
+    }
+    lines.push(`${spec.body_key} = ${tomlMultiline(out)}`);
+    return { filename: `${name}${spec.ext}`, content: lines.join('\n') + '\n', native: true, readonly };
+  }
+
+  if (spec.format !== 'md') {
+    return { filename: `${name}.md`, content: out, native: false, dropped: keys.map(([k]) => k) };
+  }
+
+  const allowed = spec.frontmatter;
+  const kept = keys.filter(([k]) => allowed.includes(k));
+  for (const [k, v] of Object.entries(spec.defaults || {})) {
+    if (!kept.some(([kk]) => kk === k)) kept.push([k, v]);
+  }
+  if (readonly && spec.readonly_key && !kept.some(([k]) => k === spec.readonly_key)) {
+    kept.push([spec.readonly_key, spec.readonly_value]);
+  }
+  const dropped = keys.filter(([k]) => !allowed.includes(k)).map(([k]) => k);
+  return { filename: `${name}${spec.ext || '.md'}`, content: emitFrontmatter(kept) + out, native: true, dropped, readonly };
+}
+
+module.exports = {
+  assertSupported,
+  stateDir,
+  configPath,
+  listRuntimes,
+  loadRuntime,
+  detectRuntimes,
+  resolvePaths,
+  expandHome,
+  displayPath,
+  applyConditionals,
+  testCondition,
+  parseFrontmatter,
+  emitFrontmatter,
+  preamble,
+  renderCommand,
+  renderAgent,
+};

package/core/agents/implementer.template.md

@@ -72,9 +72,9 @@ tools are unavailable or come up empty.
 2. Implement until green, following your baked conventions.
 3. Refactor to the conventions. Keep tests green.
 4. **Lint + format before handoff:** run your surface's lint and fix every issue. If the project
-   registers a PostToolUse format hook (see `.claude/settings.json`), your files are already
-   formatted on every write — skip `format_cmd`; otherwise run it too. Code you hand off must be
-   lint-clean and formatted.
+   registers a format-on-write hook (Claude Code: `PostToolUse` in `settings.json`), your files are
+   already formatted on every write — skip `format_cmd`; otherwise run it too. Code you hand off must
+   be lint-clean and formatted.
 
 **Run commands bridled — always.** Your surface's `test_quiet_cmd`/`lint_quiet_cmd` in `PIPELINE.md`
 are the forms you execute (dot reporter / failures-only); when a quiet variant is empty or absent,

package/core/agents/release.md

@@ -11,9 +11,6 @@ committing, pushing, and opening the PR. You do **not** write features.
 
 > **First action, always:** read `PIPELINE.md` §`pipeline-profile` → `vcs` (host, remote,
 > default_branch, feature_branch_prefix) and `name`. Those drive the branch, PR base, and remote URL.
->
-> The PR-body template path (`.claude/templates/pr-body.md`) resolves to `~/.claude/templates/pr-body.md`
-> when the core is installed globally — read whichever exists.
 
 ## You must NEVER
 
@@ -23,11 +20,17 @@ committing, pushing, and opening the PR. You do **not** write features.
   on pushed commits), or delete branches.
 - Run anything in `PIPELINE.md` §`gate.deny` (destructive DB/history).
 - Commit secrets — inspect `git status`/`git diff` and refuse if `.env` or credentials are staged.
+- **Author or edit a release note** (`.changeset/*.md` or whatever `PIPELINE.md` §`release_notes`
+  declares). The lead writes it before dispatching you; picking a bump level is project policy, not a
+  git ritual. You only **stage** it. If `release_notes.enabled` and the file is absent, say so in your
+  report instead of inventing one — the lead fixes it.
 
 ## Your inputs
 
 1. The spec path `specs/<id>.md` (title, goal, contract — for the PR body).
 2. `feature_id` and the branch `<vcs.feature_branch_prefix><id>`.
+3. If `PIPELINE.md` §`release_notes.enabled`, the already-written note at
+   `<release_notes.dir>/<release_notes.filename>` — stage it with everything else.
 
 ## Steps
 
@@ -39,7 +42,7 @@ committing, pushing, and opening the PR. You do **not** write features.
 3. `git push -u origin <branch>` (plain push, no force).
 4. Open the PR against `vcs.default_branch`:
    - `vcs.host: github` and `gh` available → `gh pr create --base <default_branch> --head <branch>` with a
-     title + body filled from `.claude/templates/pr-body.md`.
+     title + body filled from `<core>/templates/pr-body.md`.
    - Otherwise (no `gh`, or `host: gitlab/none`) → do NOT fail: push, then emit the compare URL
      (`https://github.com/<vcs.remote>/compare/<default_branch>...<branch>?expand=1`, or the host's
      equivalent) and print the drafted PR title + body for the human to open.

package/core/agents/review.md

@@ -5,8 +5,16 @@ tools: Read, Grep, Glob, mcp__serena
 model: sonnet
 ---
 
-You are the **review** agent for one feature. You are **read-only by construction** — no Write, Edit,
-or Bash. You never fix anything; you only report. Your output drives the human's fix loop, so it must
+You are the **review** agent for one feature.
+<!-- cohorte:if tool_restriction -->
+You are **read-only by construction** — no Write, Edit, or Bash.
+<!-- cohorte:else -->
+You are read-only **by discipline**: this runtime does not take your write tools away, so the
+constraint holds only because you hold it. For the whole of this review you do not edit a single file,
+run a single fix, or stage anything — a reviewer who fixes what they find destroys the evidence the
+fix loop runs on, and silently converts a finding into an unreviewed change.
+<!-- cohorte:endif -->
+You never fix anything; you only report. Your output drives the human's fix loop, so it must
 be precise and self-contained.
 
 > **First action, always:** read `PIPELINE.md` — the machine block for the `surfaces`, `contract`,

package/core/commands/cohorte-audit.md

@@ -11,9 +11,11 @@ analyze only — no fixes (those go through `/cohorte-refactor`).
 > `specs/_decisions.md` §Live if it exists (SCHEMA.md §Decisions): those standing decisions are part
 > of the rulebook you audit against, and code that contradicts one is a finding like any other.
 >
+<!-- cohorte:if workflows -->
 > **Workflow variant** (opt-in — SCHEMA.md §Workflows): on Claude Code ≥ 2.1.154 with workflows
 > enabled, the human can ask to "run the audit workflow" (`<core>/workflows/audit.js` — one auditor
 > per domain, concurrent). This conversational path stays the default and the fallback.
+<!-- cohorte:endif -->
 
 ## 1. Mechanical gates (you run these — Bash)
 

package/core/commands/cohorte-brainstorm.md

@@ -17,13 +17,10 @@ at Finish, when a board is configured.
 > needs to overturn one must say which line, out loud, so the human decides it here rather than
 > discovering the contradiction at `/cohorte-spec`.
 >
-> Template paths below (`.claude/templates/…`) resolve to `~/.claude/templates/…` when the core is
-> installed globally — read whichever exists.
->
 > **Kanban** (SCHEMA.md §Kanban): every card move below is one call —
 > `<core>/pipeline/scripts/kanban-move.sh auto <feature_id> <stage> [--title "<human title>"]`, with
-> `<core>` = `.claude` bundled / `~/.claude` global (probe with `test -x`). `auto` resolves the
-> board from `~/.claude/cohorte.config.yaml` itself and exits 0 with a `kanban: <reason>` line when
+> `auto` resolves the
+> board from `<config>` itself and exits 0 with a `kanban: <reason>` line when
 > none resolves — so **never decide "no board is configured" without running it**. Reading the Ideas
 > column at Start still needs the board path: get it from a `kanban-move.sh` run, or grep the config
 > for `boards[<PIPELINE name>]`.
@@ -51,7 +48,7 @@ screens, risks, and what's explicitly out.
 ## Finish
 
 When the human is satisfied, produce the **brainstorm return** by filling
-`.claude/templates/brainstorm-return.md` and **staging it to
+`<core>/templates/brainstorm-return.md` and **staging it to
 `specs/reports/<feature_id>-brainstorm.md`** (the gitignored buffer dir — `/cohorte-spec` reads it from there
 when invoked with no paste). In chat print only a 3-line summary + the path. Tell them to run `/cohorte-spec`
 — **recommend a `/clear` first**, the return is staged on disk (pasting it remains a fallback).

package/core/commands/cohorte-build.md

@@ -11,8 +11,7 @@ You are the **lead**. Build feature **$ARGUMENTS** from its frozen spec.
 > re-read if it's already in your context this session and unmodified since._
 >
 > **Kanban** (SCHEMA.md §Kanban): once §1 confirms the frozen spec, run
-> `<core>/pipeline/scripts/kanban-move.sh auto $ARGUMENTS building` (`<core>` = `.claude` bundled /
-> `~/.claude` global — probe with `test -x`). `auto` resolves the board from the config itself and
+> `<core>/pipeline/scripts/kanban-move.sh auto $ARGUMENTS building`. `auto` resolves the board from the config itself and
 > exits 0 with a `kanban: <reason>` line when there is none — so **never decide "no board is
 > configured" without running it**. That inference, not a missing board, is what used to freeze
 > cards mid-pipeline.
@@ -20,9 +19,9 @@ You are the **lead**. Build feature **$ARGUMENTS** from its frozen spec.
 ## 1. Load & check
 
 - Check the spec front-matter FIRST — `grep '^status:' specs/$ARGUMENTS.md` (or Read with a ~15-line
-  limit) — before any full read. Buildable statuses are `frozen`, `in-review` and `in-progress` (the
-  last one means a `/cohorte-loop` is or was driving this spec — SCHEMA.md §Spec status). `blocked` means a
-  loop gave up here: say so, and route by the spec's `## Remediation` — open items ⇒ `/cohorte-fix`, none ⇒
+  limit) — before any full read. Buildable statuses are `frozen`, `in-review` and `in-progress`
+  (SCHEMA.md §Spec status). `blocked` means a previous round gave up here: say so, and route by the
+  spec's `## Remediation` — open items ⇒ `/cohorte-fix`, none ⇒
   continue this build. Anything else (`draft`, missing, `shipped`) ⇒ stop and tell the human to run
   `/cohorte-spec` first. Only then read the body, selectively: front-matter, §5 contract, the surface
   task sections, and `## Remediation` (fall back to a full read if the spec doesn't follow the
@@ -58,13 +57,13 @@ Map every area the spec touches (§5 contract + each surface's tasks + touched p
 For each surface to add: infer its `key`, `path`, `label`, `agent`, `tools`, `model`, `*_cmd`s, and
 `uses_design` (mirror a sibling surface), show the human a one-line proposal, and on go-ahead **render it now** per
 SCHEMA.md §"Rendering / reconciling a surface agent" — write the `surfaces[]` entry + §Conventions/§Testing
-stanza into `PIPELINE.md`, render `.claude/agents/<agent>.md` from the implementer template, applying the
+stanza into `PIPELINE.md`, render `<agents>/<agent>.md` from the implementer template, applying the
 shared-code rule (shared trees get a single-owner surface; cross-slice shapes go through the contract).
 This is the automatic path: you don't send the human back to `/cohorte-init-pipeline`. If nothing new is needed,
 say so and continue. Dispatch (§3) then covers the reconciled surface list.
 
 **Adding or splitting a surface is an architectural decision** — append ONE line for it to
-`specs/_decisions.md` §Live (SCHEMA.md §Decisions; create from `.claude/templates/decisions.template.md`
+`specs/_decisions.md` §Live (SCHEMA.md §Decisions; create from `<core>/templates/decisions.template.md`
 if absent), area `surfaces`, e.g.
 `- <date> · surfaces · <key> owns <path>, single owner of <what> — because <the boundary reason> · $ARGUMENTS`.
 One `>>` in the Bash call you're already making. Nothing added ⇒ nothing to append.
@@ -94,8 +93,8 @@ good idea (that was `/cohorte-brainstorm`), never by re-reading files you don't
 
 Write the machine-readable verdict to `specs/reports/$ARGUMENTS.readiness.json` (overwrite,
 `mkdir -p specs/reports` first — the same gitignored buffer dir `/cohorte-review` stages into, which may not
-exist yet on a first build) — on **every** build, including `READY`. It is the only channel between this gate and a driver (`/cohorte-loop`),
-which parses no prose:
+exist yet on a first build) — on **every** build, including `READY`. It is the only channel between
+this gate and any automated driver, which parses no prose:
 
 ```json
 { "id": "$ARGUMENTS", "phase": "readiness", "ts": "<ISO>", "verdict": "RESERVATIONS",
@@ -129,7 +128,7 @@ wall-clock start — no separate timing call).
 
 ## 3. Dispatch one implementer per surface — IN PARALLEL
 
-Spawn every surface's agent in a **single message** (one Task call each) so they run concurrently —
+Spawn every surface's agent in a **single message** (one dispatch each) so they run concurrently —
 NEVER serially: build wall-clock must be the slowest surface, not the sum. Use
 the reconciled `surfaces` list from §1.5 (existing + any just-rendered). Give EACH only what a stateless
 agent needs — re-supply everything every time, as **exact file paths** (spec, contract, the surface's
@@ -153,11 +152,11 @@ tree. For each surface in `surfaces`:
 
 ## 3.5 Roll call — account for EVERY dispatch before integrating
 
-A subagent can die: a rate limit mid-run, a transport error after retries, its own context exhausted.
+A surface's work can die: a rate limit mid-run, a transport error after retries, context exhausted.
 When it does, it returns **nothing** — and nothing is byte-identical to "a clean surface with nothing
 to report". Silence is not a green light; treat it as the failure it is (SCHEMA.md §Dead agents).
 
-- **Roll call.** Every surface you dispatched in §3 must come back with a handoff in the format its
+- **Roll call.** Every surface handled in §3 must come back with a handoff in the format its
   agent instructions define. Missing, empty, or truncated mid-sentence ⇒ that surface is **dead**.
 - **Never infer success from silence,** and never speak for a dead agent — you did not see its work.
 - **Retry that surface ONCE, alone.** Re-dispatch it with the byte-identical §3 prompt. The other
@@ -174,9 +173,9 @@ to report". Silence is not a green light; treat it as the failure it is (SCHEMA.
 When all return, flag any contract mismatch or failing test from the handoffs; otherwise print one
 status line per surface (`<key> · tests pass/fail · <n> TODOs`) — do not restate handoff content.
 A dead surface (§3.5) prints `<key> · DEAD — unverified` and **the batch is never reported as ok**.
-Append **ONE line for the batch** to the **main checkout's** `.claude/pipeline-metrics.jsonl` —
+Append **ONE line for the batch** to the **main checkout's** `<state>/pipeline-metrics.jsonl` —
 NOT the worktree's, which dies at teardown while metrics must accumulate across features. Resolve
-it from anywhere: `$(dirname "$(git rev-parse --git-common-dir)")/.claude/pipeline-metrics.jsonl`
+it from anywhere: `$(dirname "$(git rev-parse --git-common-dir)")/<state>/pipeline-metrics.jsonl`
 (in the main checkout this resolves to itself). Create it if absent; it must be gitignored.
 Compute the elapsed time in the same Bash call
 (`echo "{...\"seconds\":$(($(date +%s)-<start epoch from §2>)),...}" >> …`):
@@ -189,9 +188,7 @@ never sees your chat:
 `{"id":"$ARGUMENTS","phase":"build","ts":"<ISO>","surfaces":{"<key>":"ok|error|dead",…},"dead":["<key>",…]}`
 — this is the evidence SCHEMA.md §Specialization asks for before splitting a surface. In the same
 Bash call, chain the opt-in usage ping — **the shared form every phase command reuses**:
-`<core>/pipeline/scripts/telemetry-send.sh <phase> "$ARGUMENTS" <seconds> "<results>" || true`
-(`<core>` = `~/.claude` global / `.claude` bundled; here `<phase>` = `build`, `<results>` =
-`<ok,ok|error,…>`) — a silent no-op unless the human explicitly consented (SCHEMA.md §Telemetry);
+`<core>/pipeline/scripts/telemetry-send.sh <phase> "$ARGUMENTS" <seconds> "<results>" || true` — a silent no-op unless the human explicitly consented (SCHEMA.md §Telemetry);
 never ask about consent here. `/cohorte-review` and `/cohorte-fix` chain the same line with their own
 phase + results. The `|| true` swallows a **missing** script too, so a half-copied core goes
 silent rather than loud — `/cohorte-doctor` check 1 is what catches that.