contextdevkit 1.8.0

package/templates/contextkit/tools/scripts/session-reindex.mjs

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+/**
+ * Regenerates `contextkit/memory/SESSIONS.md` as an INDEX of the per-session
+ * markdown files under `contextkit/memory/sessions/`.
+ *
+ * Why a derived index? With multiple parallel sessions, a monolithic file is
+ * a merge-conflict hotspot. Each session writes its OWN file; the aggregate
+ * is rebuilt from filesystem state.
+ *
+ * Entry naming: `<YYYY-MM-DD>-<NN>-<slug>.md`
+ *   - NN: zero-padded monotonic session number.
+ *   - slug: `[a-z0-9._-]` (kebab-case + version dots/underscores).
+ *
+ * Usage:  node contextkit/tools/scripts/session-reindex.mjs
+ *         (also wired into the pre-commit git hook)
+ */
+import { readdir, readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { pathsFor } from '../../runtime/config/paths.mjs';
+
+const ROOT = process.cwd();
+const P = pathsFor(ROOT);
+const SESSIONS_DIR = P.sessions;
+const INDEX_PATH = P.sessionsIndex;
+const ENTRY_PATTERN = /^(\d{4}-\d{2}-\d{2})-(\d{2,})-([a-z0-9._-]+)\.md$/;
+
+async function extractTitle(filePath, fallbackSlug) {
+  try {
+    const content = await readFile(filePath, 'utf-8');
+    const heading = content.split('\n').find((l) => l.startsWith('# '));
+    return heading ? heading.slice(2).trim() : fallbackSlug;
+  } catch {
+    return fallbackSlug;
+  }
+}
+
+async function listEntries() {
+  let files = [];
+  try {
+    files = await readdir(SESSIONS_DIR);
+  } catch {
+    return [];
+  }
+  const entries = [];
+  for (const filename of files) {
+    const match = ENTRY_PATTERN.exec(filename);
+    if (!match) continue;
+    const [, date, numberStr, slug] = match;
+    const title = await extractTitle(resolve(SESSIONS_DIR, filename), slug);
+    entries.push({ filename, date, number: Number.parseInt(numberStr, 10), slug, title });
+  }
+  entries.sort((a, b) => (b.number !== a.number ? b.number - a.number : b.date.localeCompare(a.date)));
+  return entries;
+}
+
+function buildIndex(entries) {
+  const out = [];
+  out.push('# Session History');
+  out.push('');
+  out.push('> ⚠️  **AUTO-GENERATED FILE — DO NOT EDIT BY HAND**.');
+  out.push('> Each session lives in its own file under `contextkit/memory/sessions/`.');
+  out.push('> Regenerated by `session-reindex` (also runs on pre-commit).');
+  out.push('');
+  out.push('Register a new session with `/log-session`.');
+  out.push('');
+  if (entries.length === 0) {
+    out.push('_(No sessions registered yet.)_');
+    out.push('');
+    return out.join('\n');
+  }
+  out.push(`Total registered sessions: **${entries.length}** (newest first).`);
+  out.push('');
+  out.push('| # | Date | Title | File |');
+  out.push('| --- | --- | --- | --- |');
+  for (const e of entries) {
+    out.push(`| ${String(e.number).padStart(2, '0')} | ${e.date} | ${e.title} | [${e.filename}](sessions/${e.filename}) |`);
+  }
+  out.push('');
+  return out.join('\n');
+}
+
+async function main() {
+  const entries = await listEntries();
+  await writeFile(INDEX_PATH, buildIndex(entries), 'utf-8');
+  console.log(`✅ SESSIONS.md regenerated — ${entries.length} entries indexed.`);
+}
+
+main().catch((err) => {
+  console.error('❌ Failed to reindex sessions:', err);
+  process.exit(1);
+});

package/templates/contextkit/tools/scripts/setup-complete.mjs

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * Marks ContextDevKit onboarding complete (stops the first-run trigger) and,
+ * optionally, applies stack-tuned config produced by `detect-stack.mjs`.
+ *
+ * Usage:
+ *   node contextkit/tools/scripts/setup-complete.mjs
+ *       → just flips config.setup.completed = true
+ *
+ *   node contextkit/tools/scripts/setup-complete.mjs --detect
+ *       → runs detect-stack.mjs itself and merges its suggestions, then flips
+ *         the flag. Preferred — avoids shell-redirect encoding pitfalls.
+ *
+ *   node contextkit/tools/scripts/setup-complete.mjs --apply <report.json>
+ *       → merges suggestions from a pre-generated report file, then flips.
+ *
+ * Keeping this in a script (not free-form JSON editing) guarantees the config
+ * stays valid — the file is the contract the hooks read.
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { parseJsonSafe, readJsonSafe } from '../../runtime/hooks/safe-io.mjs';
+import { pathsFor } from '../../runtime/config/paths.mjs';
+
+const ROOT = process.cwd();
+const CONFIG = pathsFor(ROOT).config;
+
+const readJson = (path, fallback = null) => readJsonSafe(path, fallback);
+
+function runDetector() {
+  try {
+    const out = execFileSync('node', ['contextkit/tools/scripts/detect-stack.mjs'], { cwd: ROOT, encoding: 'utf-8' });
+    return parseJsonSafe(out, null);
+  } catch (err) {
+    console.error(`detect-stack failed: ${err?.message ?? err}`);
+    return null;
+  }
+}
+
+function main() {
+  const cfg = existsSync(CONFIG) ? readJson(CONFIG, {}) : {};
+
+  const detect = process.argv.includes('--detect');
+  const applyIdx = process.argv.indexOf('--apply');
+  if (detect || applyIdx !== -1) {
+    const report = detect ? runDetector() : readJson(resolve(ROOT, process.argv[applyIdx + 1] ?? ''), null);
+    const suggested = report?.suggested;
+    if (suggested) {
+      cfg.ledger = cfg.ledger || {};
+      if (Array.isArray(suggested.ledger?.important)) cfg.ledger.important = suggested.ledger.important;
+      if (Array.isArray(suggested.ledger?.irrelevant)) cfg.ledger.irrelevant = suggested.ledger.irrelevant;
+      if (!Array.isArray(cfg.ledger.registration)) cfg.ledger.registration = ['contextkit/memory/SESSIONS.md', 'docs/CHANGELOG.md'];
+      cfg.l5 = cfg.l5 || {};
+      if (Array.isArray(suggested.highRiskPaths)) cfg.l5.highRiskPaths = suggested.highRiskPaths;
+      cfg.qa = cfg.qa || {};
+      if (Array.isArray(suggested.qaCriticalPaths)) cfg.qa.criticalPaths = suggested.qaCriticalPaths;
+      console.log(`Applied suggestions: ${cfg.ledger.important.length} important paths, ${cfg.l5.highRiskPaths.length} high-risk paths, ${(cfg.qa.criticalPaths || []).length} qa-critical paths.`);
+    } else {
+      console.log('No report supplied or report had no suggestions — only flipping setup flag.');
+    }
+  }
+
+  cfg.setup = { ...(cfg.setup || {}), completed: true, completedAt: new Date().toISOString() };
+  writeFileSync(CONFIG, JSON.stringify(cfg, null, 2) + '\n', 'utf-8');
+  console.log('✅ ContextDevKit setup marked complete. The first-run trigger will no longer fire.');
+}
+
+main();

package/templates/contextkit/tools/scripts/squad-meta.mjs

@@ -0,0 +1,23 @@
+/**
+ * Shared squad detection — used by squad.mjs (/squad) and agent-tuning.mjs
+ * (/tune-agents) so the rule lives in exactly one place:
+ *   qa-* → qa-team; otherwise the `(<name> squad)` / `(<name>-team)` tag in the
+ *   agent's description frontmatter; falls back to devteam.
+ * Zero-dependency, defensive (never throws).
+ */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+/** @param {string} agentsDir absolute path to `.claude/agents` @param {string} agent bare name */
+export function squadOf(agentsDir, agent) {
+  if (/^qa-/.test(agent)) return 'qa-team';
+  let frontmatter = null;
+  try {
+    frontmatter = readFileSync(resolve(agentsDir, `${agent}.md`), 'utf-8').match(/^---\n([\s\S]*?)\n---/);
+  } catch {
+    return 'devteam';
+  }
+  const desc = (frontmatter && /description:\s*(.*)/.exec(frontmatter[1])?.[1]) || '';
+  const tag = desc.match(/\(([a-z][a-z0-9-]*?)(?: squad)?\)\s*$/i);
+  return tag ? tag[1] : 'devteam';
+}

package/templates/contextkit/tools/scripts/squad-pipeline-condition.mjs

@@ -0,0 +1,192 @@
+/**
+ * Whitelisted condition parser + evaluator for the squad pipeline DSL
+ * ([ADR-0015](../../memory/decisions/0015-pipeline-dsl-working-stage-and-multi-session-work-claims.md) Part A).
+ *
+ * Single responsibility: turn a `condition:` string from `pipeline.yaml` into
+ * a tiny AST, then evaluate it against the pipeline context. No arbitrary
+ * expression evaluation, no function calls, no boolean chaining — by design.
+ *
+ * Grammar (full reference in docs/SQUAD-PIPELINE-FORMAT.md §condition):
+ *   condition := dotted_id <op> literal
+ *              | dotted_id ".length" <op> int
+ *   dotted_id := identifier ( "." identifier )*
+ *   op        := "==" | "!=" | ">=" | "<=" | ">" | "<"
+ *   literal   := string | int | float | bool | null
+ *
+ * API:
+ *   parseCondition(expr) → { ok: true, ast } | { ok: false, reason }
+ *   evalCondition(ast, ctx) → boolean
+ *
+ * Pure, zero-dep. Stays under the 280-line budget by keeping the lexer and
+ * the comparator inline (one small file, two ~40-line halves).
+ */
+
+const OP_RE = /^(==|!=|>=|<=|>|<)/;
+const IDENT_RE = /^[a-zA-Z_][a-zA-Z0-9_]*/;
+const INT_RE = /^-?\d+(?![.\d])/;
+const FLOAT_RE = /^-?\d+\.\d+/;
+const STRING_RE = /^"([^"]*)"|^'([^']*)'/;
+const VALID_OPS = ['==', '!=', '>=', '<=', '>', '<'];
+
+/**
+ * Parses a condition expression into an AST.
+ *
+ * @param {string} expr — the raw `condition:` value from `pipeline.yaml`
+ * @returns {{ ok: true, ast: { path: string[], isLength: boolean, op: string, literal: unknown } }
+ *        | { ok: false, reason: string }}
+ */
+export function parseCondition(expr) {
+  if (typeof expr !== 'string' || expr.trim() === '') {
+    return { ok: false, reason: 'empty condition' };
+  }
+
+  let src = expr.trim();
+
+  // --- identifier path -----------------------------------------------------
+  const path = [];
+  const firstId = src.match(IDENT_RE);
+  if (!firstId) return { ok: false, reason: 'expected identifier' };
+  path.push(firstId[0]);
+  src = src.slice(firstId[0].length);
+
+  while (src.startsWith('.')) {
+    src = src.slice(1);
+    const nextId = src.match(IDENT_RE);
+    if (!nextId) return { ok: false, reason: 'expected identifier after "."' };
+    path.push(nextId[0]);
+    src = src.slice(nextId[0].length);
+  }
+
+  const isLength = path[path.length - 1] === 'length' && path.length > 1;
+
+  // --- operator ------------------------------------------------------------
+  src = src.trimStart();
+  const opMatch = src.match(OP_RE);
+  if (!opMatch) {
+    return { ok: false, reason: `expected one of ${VALID_OPS.join(' / ')} after dotted_id` };
+  }
+  const op = opMatch[0];
+  src = src.slice(op.length).trimStart();
+
+  // --- literal -------------------------------------------------------------
+  const lit = parseLiteral(src);
+  if (!lit.ok) return { ok: false, reason: lit.reason };
+
+  // .length restricts the RHS to int
+  if (isLength && !Number.isInteger(lit.value)) {
+    return { ok: false, reason: '.length must be compared to an integer literal' };
+  }
+
+  // --- nothing else is allowed --------------------------------------------
+  if (lit.rest.trim() !== '') {
+    return { ok: false, reason: `unexpected trailing input: "${lit.rest.trim()}"` };
+  }
+
+  return { ok: true, ast: { path, isLength, op, literal: lit.value } };
+}
+
+/**
+ * Reads one literal off the front of `src`. Returns the value and the
+ * remainder so the caller can assert nothing trails.
+ *
+ * @param {string} src
+ * @returns {{ ok: true, value: unknown, rest: string } | { ok: false, reason: string }}
+ */
+function parseLiteral(src) {
+  if (src.startsWith('true')) {
+    return { ok: true, value: true, rest: src.slice(4) };
+  }
+  if (src.startsWith('false')) {
+    return { ok: true, value: false, rest: src.slice(5) };
+  }
+  if (src.startsWith('null')) {
+    return { ok: true, value: null, rest: src.slice(4) };
+  }
+
+  const str = src.match(STRING_RE);
+  if (str) return { ok: true, value: str[1] ?? str[2], rest: src.slice(str[0].length) };
+
+  const flt = src.match(FLOAT_RE);
+  if (flt) return { ok: true, value: Number(flt[0]), rest: src.slice(flt[0].length) };
+
+  const int = src.match(INT_RE);
+  if (int) return { ok: true, value: parseInt(int[0], 10), rest: src.slice(int[0].length) };
+
+  return { ok: false, reason: 'expected literal (string / int / float / bool / null)' };
+}
+
+/**
+ * Resolves a dotted path against `ctx`. Returns `undefined` on any miss.
+ * `.length` is special-cased for arrays and strings.
+ *
+ * @param {string[]} path
+ * @param {Record<string, unknown>} ctx
+ * @returns {unknown}
+ */
+function resolve(path, ctx) {
+  let cur = ctx;
+  for (let i = 0; i < path.length; i += 1) {
+    const key = path[i];
+    if (cur == null || typeof cur !== 'object') return undefined;
+    if (key === 'length' && i === path.length - 1 && i > 0) {
+      if (typeof cur === 'string' || Array.isArray(cur)) return cur.length;
+      return undefined;
+    }
+    cur = cur[key];
+  }
+  if (typeof cur === 'function') return undefined;
+  return cur;
+}
+
+/**
+ * Evaluates a parsed condition against `ctx`. The grammar guarantees the
+ * AST is well-formed; the only runtime concerns are `undefined`-resolution
+ * and the no-coercion compare semantics.
+ *
+ * Rules:
+ *   - `undefined <op> <literal>` → false (always).
+ *   - `==` / `!=` use strict equality (no coercion).
+ *   - `>` / `<` / `>=` / `<=` require both sides to be `typeof "number"`;
+ *     otherwise → false.
+ *
+ * @param {{ path: string[], isLength: boolean, op: string, literal: unknown }} ast
+ * @param {Record<string, unknown>} ctx
+ * @returns {boolean}
+ */
+export function evalCondition(ast, ctx) {
+  const left = resolve(ast.path, ctx ?? {});
+  if (left === undefined) return false;
+  const right = ast.literal;
+  switch (ast.op) {
+    case '==':
+      return left === right;
+    case '!=':
+      return left !== right;
+    case '>':
+      return typeof left === 'number' && typeof right === 'number' && left > right;
+    case '<':
+      return typeof left === 'number' && typeof right === 'number' && left < right;
+    case '>=':
+      return typeof left === 'number' && typeof right === 'number' && left >= right;
+    case '<=':
+      return typeof left === 'number' && typeof right === 'number' && left <= right;
+    default:
+      return false;
+  }
+}
+
+/**
+ * One-shot helper: parse + evaluate. Useful in tests and for the engine
+ * when it doesn't need to cache the AST.
+ *
+ * @param {string} expr
+ * @param {Record<string, unknown>} ctx
+ * @returns {boolean}
+ * @throws {Error} if the expression refuses to parse (grammar violation —
+ *   the engine catches this and exits 1).
+ */
+export function parseAndEval(expr, ctx) {
+  const parsed = parseCondition(expr);
+  if (!parsed.ok) throw new Error(`condition refused: ${parsed.reason}`);
+  return evalCondition(parsed.ast, ctx);
+}

package/templates/contextkit/tools/scripts/squad-pipeline.mjs

@@ -0,0 +1,301 @@
+#!/usr/bin/env node
+/**
+ * squad-pipeline — engine for the declarative squad pipeline DSL
+ * ([ADR-0015](../../memory/decisions/0015-pipeline-dsl-working-stage-and-multi-session-work-claims.md) Part A).
+ *
+ * Reads `<contextkit>/squads/<squad>/pipeline.yaml`, validates it against the
+ * whitelisted grammar (see `docs/SQUAD-PIPELINE-FORMAT.md`), and — with
+ * `--dry-run` — walks the graph printing the would-be execution order.
+ *
+ * Refusal modes (see the spec for the full table):
+ *   • `yaml` not installed                   → exit 0 (informative; opt-in feature)
+ *   • pipeline.yaml malformed                → exit 1
+ *   • vendor model name instead of tier      → exit 1
+ *   • condition grammar violation            → exit 1
+ *   • on_reject target missing               → exit 1
+ *   • on_reject without max_review_cycles    → exit 1
+ *   • agent has no briefing                  → exit 1
+ *
+ * Usage:
+ *   node <path>/squad-pipeline.mjs <squad> [--dry-run]
+ *
+ * Cohesion note: kept as one file (~250 lines) because validation, dry-run
+ * printing, and the path-discovery glue all consume the same parsed
+ * pipeline + the same context object. Splitting along those seams would
+ * scatter one pipeline lifecycle across three files with shared state in
+ * each — the constitution rewards keeping a single coherent unit together.
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadYaml } from '../../squads/agent-forge/lib/yaml.mjs';
+import { parseCondition, evalCondition } from './squad-pipeline-condition.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const SCRIPT_DIR = dirname(__filename);
+const CONTEXTKIT_ROOT = resolve(SCRIPT_DIR, '..', '..');           // .../[templates/]contextkit
+const REPO_ROOT = resolve(CONTEXTKIT_ROOT, '..');                   // .../[repo or project]
+
+const VALID_TIERS = new Set(['fast', 'powerful', 'reasoning']);
+const VALID_EXECUTIONS = new Set(['inline', 'subagent']);
+const REQUIRED_AGENT_FIELDS = ['id', 'agent', 'execution', 'model_tier'];
+const REQUIRED_CHECKPOINT_FIELDS = ['id', 'type', 'outputFile'];
+
+/**
+ * Discovers the squad's `pipeline.yaml`. Handles both layouts:
+ *   • source-tree:    <repo>/templates/contextkit/squads/<squad>/pipeline.yaml
+ *   • installed:      <project>/contextkit/squads/<squad>/pipeline.yaml
+ *
+ * @param {string} squad
+ * @returns {string | null} absolute path, or null when not found
+ */
+function findPipelineFile(squad) {
+  const candidate = resolve(CONTEXTKIT_ROOT, 'squads', squad, 'pipeline.yaml');
+  return existsSync(candidate) ? candidate : null;
+}
+
+/**
+ * Discovers the agents directory. Same dual-layout handling.
+ * @returns {string | null}
+ */
+function findAgentsDir() {
+  const installed = resolve(REPO_ROOT, '.claude/agents');
+  if (existsSync(installed)) return installed;
+  const source = resolve(REPO_ROOT, 'templates/claude/agents');
+  if (existsSync(source)) return source;
+  return null;
+}
+
+/**
+ * Lists agent briefing ids (basename without `.md`). Empty when the
+ * directory cannot be read — selfcheck handles the diagnostic.
+ *
+ * @param {string | null} dir
+ * @returns {Set<string>}
+ */
+function listAgentIds(dir) {
+  if (!dir) return new Set();
+  try {
+    return new Set(readdirSync(dir).filter((f) => f.endsWith('.md')).map((f) => f.slice(0, -3)));
+  } catch {
+    return new Set();
+  }
+}
+
+/**
+ * Validates one step's shape and grammar. Returns an array of error strings.
+ *
+ * @param {Record<string, unknown>} step
+ * @param {Set<string>} stepIds — defined ids in the whole pipeline
+ * @param {Set<string>} agentIds — agent briefings present on disk
+ * @returns {string[]}
+ */
+function validateStep(step, stepIds, agentIds) {
+  const errors = [];
+  const isCheckpoint = step.type === 'checkpoint';
+  const required = isCheckpoint ? REQUIRED_CHECKPOINT_FIELDS : REQUIRED_AGENT_FIELDS;
+  for (const key of required) {
+    if (step[key] == null) errors.push(`step ${step.id ?? '?'}: missing required field "${key}"`);
+  }
+
+  if (!isCheckpoint) {
+    if (step.type && step.type !== 'checkpoint') {
+      errors.push(`step ${step.id}: unknown type "${step.type}"`);
+    }
+    if (step.execution && !VALID_EXECUTIONS.has(step.execution)) {
+      errors.push(`step ${step.id}: execution must be inline | subagent`);
+    }
+    if (step.model_tier && !VALID_TIERS.has(step.model_tier)) {
+      errors.push(`step ${step.id}: model_tier must be fast | powerful | reasoning`);
+    }
+    if (typeof step.model === 'string') {
+      errors.push(`step ${step.id}: vendor model names are forbidden; use model_tier`);
+    }
+    if (step.agent && agentIds.size > 0 && !agentIds.has(String(step.agent))) {
+      errors.push(`step ${step.id}: agent "${step.agent}" has no briefing under .claude/agents/`);
+    }
+  }
+
+  if (typeof step.condition === 'string') {
+    const parsed = parseCondition(step.condition);
+    if (!parsed.ok) errors.push(`step ${step.id}: condition refused — ${parsed.reason}`);
+  }
+
+  if (step.on_reject != null) {
+    if (!stepIds.has(String(step.on_reject))) {
+      errors.push(`step ${step.id}: on_reject target "${step.on_reject}" not found`);
+    }
+    if (!Number.isInteger(step.max_review_cycles) || step.max_review_cycles < 1) {
+      errors.push(`step ${step.id}: on_reject requires max_review_cycles (integer >= 1)`);
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Validates the whole pipeline object. Throws on the first failure with a
+ * collected error report so callers see every problem in one shot.
+ *
+ * @param {{ squad?: string, version?: string, steps?: unknown[] }} pipeline
+ * @param {Set<string>} agentIds
+ */
+export function validatePipeline(pipeline, agentIds) {
+  const errors = [];
+  if (!pipeline || typeof pipeline !== 'object') errors.push('pipeline: missing root object');
+  if (typeof pipeline.squad !== 'string') errors.push('pipeline.squad: missing or not a string');
+  if (typeof pipeline.version !== 'string') errors.push('pipeline.version: missing or not a string');
+  if (!Array.isArray(pipeline.steps) || pipeline.steps.length === 0) errors.push('pipeline.steps: must be a non-empty array');
+
+  if (errors.length > 0) throw new Error(errors.join('\n'));
+
+  const stepIds = new Set();
+  for (const step of pipeline.steps) {
+    if (!step || typeof step !== 'object' || typeof step.id !== 'string') {
+      errors.push('step: missing id');
+      continue;
+    }
+    if (stepIds.has(step.id)) errors.push(`step ${step.id}: duplicate id`);
+    stepIds.add(step.id);
+  }
+
+  for (const step of pipeline.steps) {
+    if (!step || typeof step.id !== 'string') continue;
+    errors.push(...validateStep(step, stepIds, agentIds));
+  }
+
+  if (errors.length > 0) throw new Error(errors.join('\n'));
+}
+
+/**
+ * Walks the pipeline once, emitting one display row per step. Honours
+ * `condition` by skipping when it resolves to false against `ctx`. Honours
+ * `max_review_cycles` only as a marker — dry-run does not actually loop;
+ * the cap belongs to the executor.
+ *
+ * Marker legend (from the spec):
+ *   ✓ runs  ·  ⊘ skipped by condition  ·  ↺ has retry loop
+ *
+ * @param {{ steps: Record<string, unknown>[] }} pipeline
+ * @param {Record<string, unknown>} ctx
+ * @returns {Array<{ id: string, marker: '✓' | '⊘' | '↺', kind: string, agent: string, execution: string, tier: string, note: string }>}
+ */
+export function plan(pipeline, ctx) {
+  const rows = [];
+  for (const step of pipeline.steps) {
+    const isCheckpoint = step.type === 'checkpoint';
+    let marker = '✓';
+    let note = '';
+    if (typeof step.condition === 'string') {
+      const parsed = parseCondition(step.condition);
+      if (parsed.ok && !evalCondition(parsed.ast, ctx)) {
+        marker = '⊘';
+        note = `condition: ${step.condition} → false`;
+      }
+    }
+    if (step.on_reject) {
+      marker = marker === '⊘' ? '⊘' : '↺';
+      note = `on_reject → ${step.on_reject}, max_cycles: ${step.max_review_cycles}`;
+    }
+    rows.push({
+      id: String(step.id),
+      marker,
+      kind: isCheckpoint ? 'checkpoint' : 'agent',
+      agent: isCheckpoint ? '' : String(step.agent ?? ''),
+      execution: isCheckpoint ? '' : String(step.execution ?? ''),
+      tier: isCheckpoint ? '' : String(step.model_tier ?? ''),
+      note,
+    });
+  }
+  return rows;
+}
+
+/**
+ * Formats the dry-run plan as a single text block ready for stdout.
+ * Kept here (not in a sibling) because the marker semantics are intimate
+ * with `plan` above — separating them would require re-exporting the row
+ * shape across two files for no gain.
+ */
+function formatPlan(pipeline, rows) {
+  const lines = [`Pipeline: ${pipeline.squad} v${pipeline.version}`];
+  for (const r of rows) {
+    const fields = r.kind === 'checkpoint'
+      ? [r.marker, r.id.padEnd(28), 'checkpoint']
+      : [r.marker, r.id.padEnd(28), r.kind.padEnd(10), r.agent.padEnd(22), r.execution.padEnd(8), r.tier];
+    let line = `  ${fields.join(' ')}`;
+    if (r.note) line += `   (${r.note})`;
+    lines.push(line);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * Loads and validates a pipeline, returning the parsed object on success.
+ * Exposed so the selfcheck and the integration test can call it without
+ * spawning a process.
+ *
+ * @param {string} squad
+ * @returns {Promise<{ pipeline: object, file: string, agentsDir: string | null } | { yamlAbsent: true }>}
+ */
+export async function loadAndValidate(squad) {
+  const file = findPipelineFile(squad);
+  if (!file) throw new Error(`pipeline.yaml not found for squad "${squad}"`);
+
+  let pipeline;
+  try {
+    const text = readFileSync(file, 'utf-8');
+    pipeline = await (await loadYaml()).parse(text.replace(/^/, ''));
+  } catch (err) {
+    if (/needs the `yaml` package/.test(String(err?.message))) return { yamlAbsent: true };
+    throw new Error(`pipeline.yaml malformed: ${err?.message ?? err}`);
+  }
+
+  // Normalise: top-level may be { pipeline: {...} } or the bare pipeline body.
+  const body = pipeline?.pipeline ?? pipeline;
+  const agentsDir = findAgentsDir();
+  validatePipeline(body, listAgentIds(agentsDir));
+  return { pipeline: body, file, agentsDir };
+}
+
+async function main() {
+  const squad = process.argv[2];
+  const dryRun = process.argv.includes('--dry-run');
+
+  if (!squad) {
+    console.error('Usage: squad-pipeline.mjs <squad> [--dry-run]');
+    process.exit(1);
+  }
+
+  let result;
+  try {
+    result = await loadAndValidate(squad);
+  } catch (err) {
+    console.error(`❌ ${err?.message ?? err}`);
+    process.exit(1);
+  }
+
+  if (result.yamlAbsent) {
+    console.log(`ℹ️  pipelines are opt-in — install the optional 'yaml' dep to use them:`);
+    console.log(`   npm i yaml`);
+    console.log(`   (squad "${squad}" continues to work without the DSL.)`);
+    process.exit(0);
+  }
+
+  if (dryRun) {
+    console.log(formatPlan(result.pipeline, plan(result.pipeline, {})));
+    return;
+  }
+
+  console.log(`✅ ${squad} pipeline validated (${result.pipeline.steps.length} steps).`);
+  console.log(`   Run with --dry-run to print the would-be execution order.`);
+}
+
+// Only run when invoked as a CLI; library imports stay side-effect-free.
+// `process.argv[1]` is undefined when the module is imported via `node -e`,
+// so we guard explicitly before doing any string work.
+if (process.argv[1] && fileURLToPath(import.meta.url) === resolve(process.argv[1])) {
+  main().catch((err) => {
+    console.error(`❌ ${err?.message ?? err}`);
+    process.exit(1);
+  });
+}