contextdevkit 1.8.0

package/templates/contextkit/tools/scripts/git.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * Version-control diagnostics — facts for the `/git` skill.
+ *
+ * Reports git presence, repo/commit state, the remote + inferred provider
+ * (GitHub/GitLab/Bitbucket/Azure), whether the provider CLI (`gh`/`glab`) is
+ * installed and authenticated, the current branch, dirtiness, and ahead/behind
+ * vs upstream. `/git` reads this and suggests the exact next commands.
+ *
+ * Usage:  node contextkit/tools/scripts/git.mjs status [--json]
+ */
+import { execFileSync } from 'node:child_process';
+
+const ROOT = process.cwd();
+
+/**
+ * Hard ceiling (ms) for any git/CLI subprocess. A hung network call — `git fetch`
+ * against an unreachable remote, or `gh auth status` with no connectivity — must
+ * not freeze `/git status`. On timeout `execFileSync` throws, so `run()` returns
+ * `{ ok:false }` (the same path as a failed command) and the report degrades
+ * gracefully. Overridable via env so tests can drive the timeout path fast.
+ */
+const CMD_TIMEOUT_MS = Number.parseInt(process.env.CONTEXT_GIT_TIMEOUT_MS || '', 10) || 10000;
+
+function run(cmd, args) {
+  try {
+    return { ok: true, out: execFileSync(cmd, args, { cwd: ROOT, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'], timeout: CMD_TIMEOUT_MS }).trim() };
+  } catch (err) {
+    return { ok: false, out: '', code: err?.status };
+  }
+}
+
+function providerFromUrl(url) {
+  if (!url) return null;
+  if (/github\.com/i.test(url)) return 'github';
+  if (/gitlab/i.test(url)) return 'gitlab';
+  if (/bitbucket\.org/i.test(url)) return 'bitbucket';
+  if (/dev\.azure\.com|visualstudio\.com/i.test(url)) return 'azure';
+  return 'other';
+}
+
+function collect() {
+  const gitV = run('git', ['--version']);
+  const isRepo = run('git', ['rev-parse', '--is-inside-work-tree']).ok;
+  const hasCommits = isRepo && run('git', ['rev-parse', 'HEAD']).ok;
+  const remoteUrl = run('git', ['remote', 'get-url', 'origin']).out || null;
+  const provider = providerFromUrl(remoteUrl);
+  const branch = run('git', ['symbolic-ref', '--short', 'HEAD']).out || null;
+  const dirty = isRepo ? run('git', ['status', '--porcelain']).out.length > 0 : false;
+
+  // Provider CLIs.
+  const gh = run('gh', ['--version']).ok;
+  const ghAuth = gh ? run('gh', ['auth', 'status']).ok : false;
+  const glab = run('glab', ['--version']).ok;
+  const glabAuth = glab ? run('glab', ['auth', 'status']).ok : false;
+
+  // ahead/behind vs upstream.
+  let ahead = null;
+  let behind = null;
+  if (remoteUrl && branch) {
+    run('git', ['fetch', 'origin', '--quiet']);
+    const counts = run('git', ['rev-list', '--left-right', '--count', 'HEAD...@{u}']);
+    if (counts.ok) {
+      const [a, b] = counts.out.split(/\s+/);
+      ahead = Number.parseInt(a ?? '0', 10);
+      behind = Number.parseInt(b ?? '0', 10);
+    }
+  }
+
+  return {
+    git: gitV.ok ? gitV.out.replace('git version ', '') : null,
+    isRepo,
+    hasCommits,
+    remoteUrl,
+    provider,
+    branch,
+    dirty,
+    cli: { gh, ghAuth, glab, glabAuth },
+    ahead,
+    behind,
+  };
+}
+
+const s = collect();
+if (process.argv.includes('--json')) {
+  console.log(JSON.stringify(s, null, 2));
+} else {
+  console.log('🔧 Version control\n');
+  console.log(`git:         ${s.git ?? 'NOT INSTALLED'}`);
+  console.log(`repo:        ${s.isRepo ? (s.hasCommits ? 'yes (has commits)' : 'yes (no commits yet)') : 'NOT a git repo'}`);
+  console.log(`branch:      ${s.branch ?? '—'}${s.dirty ? ' (uncommitted changes)' : ''}`);
+  console.log(`remote:      ${s.remoteUrl ?? 'NONE'}${s.provider ? ` [${s.provider}]` : ''}`);
+  if (s.ahead != null) console.log(`sync:        ahead ${s.ahead} / behind ${s.behind}`);
+  console.log(`gh CLI:      ${s.cli.gh ? (s.cli.ghAuth ? 'installed + authed' : 'installed, NOT authed') : 'not installed'}`);
+  console.log(`glab CLI:    ${s.cli.glab ? (s.cli.glabAuth ? 'installed + authed' : 'installed, NOT authed') : 'not installed'}`);
+  if (!s.remoteUrl) console.log('\n→ No remote. Run /git to set one up (GitHub/GitLab/other) + install the CLI.');
+}

package/templates/contextkit/tools/scripts/home.mjs

@@ -0,0 +1,106 @@
+/**
+ * Home-scoped state helper — single owner of `~/.contextdevkit/` resolution +
+ * atomic write contract (ADR-0020).
+ *
+ * Why this exists:
+ *   Cross-repo registries (fleet.json), per-machine preferences, and
+ *   regenerable caches all need to live outside any single repo. Before
+ *   this helper, `fleet.mjs` resolved the path and wrote the file inline;
+ *   any future consumer would have reinvented (and likely gotten slightly
+ *   wrong) the same logic.
+ *
+ * Contract (ADR-0020):
+ *   - Lazy creation. The directory is created on demand.
+ *   - `CONTEXTDEVKIT_HOME` env var overrides the directory (for tests and
+ *     sandboxed environments).
+ *   - All files are plain JSON, UTF-8, no BOM.
+ *   - Each file declares its own `version` field. Absent = legacy /
+ *     pre-versioning (adopted on next write). An *explicitly unknown*
+ *     value triggers a timestamped `.bak.<ms>` copy and a fresh read.
+ *   - Atomic write via tmp + rename (`renameSync` after `writeFileSync`).
+ *   - Graceful refuse on every error path (rule 2 — hooks never break
+ *     real work). Returns `null` instead of throwing on read failures.
+ *
+ * Zero deps. No HTTP, no SQLite, no daemon (ADR-0020 explicitly rules
+ * those out).
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+
+const HOME_DIR_NAME = '.contextdevkit';
+const CURRENT_VERSION = 1;
+
+/**
+ * Resolve and lazily create the home-scoped state directory.
+ *
+ * Honours `CONTEXTDEVKIT_HOME` first; otherwise falls back to
+ * `~/.contextdevkit/`. The directory is created on first call; subsequent
+ * calls are silent.
+ *
+ * @returns {string}  absolute directory path
+ */
+export function resolveHome() {
+  const dir = process.env.CONTEXTDEVKIT_HOME || resolve(homedir(), HOME_DIR_NAME);
+  if (!existsSync(dir)) {
+    try { mkdirSync(dir, { recursive: true }); } catch { /* defensive */ }
+  }
+  return dir;
+}
+
+/**
+ * Read a JSON file from `~/.contextdevkit/`. Returns `null` when the file is
+ * absent, malformed, not a plain object, or written by a future version
+ * the helper does not recognise (in which case the bad file is moved to
+ * `<name>.bak.<timestamp>` so the next write starts clean).
+ *
+ * A file without a `version` field is treated as legacy and adopted —
+ * the next write stamps `version: 1`. This avoids destroying existing
+ * `fleet.json` data on first read by the new helper.
+ *
+ * @param {string} name  file name relative to the home dir (e.g. `fleet.json`)
+ * @returns {object | null}
+ */
+export function readHomeFile(name) {
+  const path = resolve(resolveHome(), name);
+  if (!existsSync(path)) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf-8').replace(/^/, ''));
+  } catch {
+    return null;
+  }
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
+  const v = parsed.version;
+  if (v !== undefined && v !== CURRENT_VERSION) {
+    try { renameSync(path, `${path}.bak.${Date.now()}`); } catch { /* defensive */ }
+    return null;
+  }
+  return parsed;
+}
+
+/**
+ * Atomically write a JSON file under `~/.contextdevkit/`. Stamps the current
+ * `version` field if absent — callers do not need to track schema
+ * versioning themselves.
+ *
+ * Atomicity: writes to `<name>.tmp.<pid>` then `renameSync`s into place,
+ * matching the kit's installer posture.
+ *
+ * @param {string} name  file name relative to the home dir
+ * @param {object} data  plain object to serialise
+ * @throws {Error}       when `data` is not a plain object
+ */
+export function writeHomeFile(name, data) {
+  if (data === null || typeof data !== 'object' || Array.isArray(data)) {
+    throw new Error('writeHomeFile: data must be a plain object');
+  }
+  const stamped = data.version === CURRENT_VERSION ? data : { version: CURRENT_VERSION, ...data };
+  const path = resolve(resolveHome(), name);
+  const tmp = `${path}.tmp.${process.pid}`;
+  writeFileSync(tmp, JSON.stringify(stamped, null, 2) + '\n', 'utf-8');
+  renameSync(tmp, path);
+}
+
+/** Current schema version recognised by this helper. Exported for selfcheck. */
+export const HOME_SCHEMA_VERSION = CURRENT_VERSION;

package/templates/contextkit/tools/scripts/mark-simulation.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * Records a `/simulate-impact` result on the current session's ledger so the
+ * Level 5 PreToolUse gate authorizes edits inside the covered paths.
+ *
+ * Usage:
+ *   node contextkit/tools/scripts/mark-simulation.mjs "<objective>" <path> [path2 ...]
+ *   node contextkit/tools/scripts/mark-simulation.mjs "BYPASS: typo fix" path/to/file
+ *
+ * Pass directory prefixes WITH a trailing slash to cover everything inside.
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { markSimulation, readLedger, toRepoRelative, writeLedger } from '../../runtime/hooks/ledger.mjs';
+import { pathsFor } from '../../runtime/config/paths.mjs';
+
+const LAST_TOUCHED = resolve(process.cwd(), '.claude/.sessions/.last-touched');
+
+async function sessionId() {
+  try {
+    return JSON.parse(await readFile(LAST_TOUCHED, 'utf-8')).sessionId;
+  } catch {
+    return `local_${process.pid}`;
+  }
+}
+
+async function main() {
+  const [objective, ...rawPaths] = process.argv.slice(2);
+  if (!objective || rawPaths.length === 0) {
+    console.error('Usage: mark-simulation.mjs "<objective>" <path> [path2 ...]');
+    process.exit(1);
+  }
+  const coveredPaths = rawPaths.map((p) => {
+    const norm = toRepoRelative(p);
+    // Preserve an explicit trailing slash (directory claim).
+    return p.endsWith('/') && !norm.endsWith('/') ? `${norm}/` : norm;
+  });
+
+  const sid = await sessionId();
+  const ledger = await readLedger(sid);
+  const predFile = await writePrediction(sid, objective, coveredPaths);
+  markSimulation(ledger, { objective, coveredPaths, predictionFile: predFile });
+  await writeLedger(sid, ledger);
+  console.log(`✅ Simulation recorded for session ${sid.slice(0, 8)} covering: ${coveredPaths.join(', ')}`);
+  if (predFile) console.log(`   📄 prediction trail: ${predFile}`);
+}
+
+/** Writes a prediction file (ancestor parity) for a later predicted-vs-actual review. */
+async function writePrediction(sid, objective, coveredPaths) {
+  const date = new Date().toISOString().slice(0, 10);
+  const slug = objective.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 40) || 'prediction';
+  const rel = `contextkit/memory/predictions/${date}-${sid.slice(0, 8)}-${slug}.md`;
+  try {
+    await mkdir(pathsFor(process.cwd()).predictions, { recursive: true });
+    await writeFile(resolve(process.cwd(), rel), [
+      `# Prediction — ${objective}`,
+      '',
+      `- **Date**: ${date}`,
+      `- **Session**: ${sid.slice(0, 8)}`,
+      `- **Covered paths**: ${coveredPaths.join(', ') || '—'}`,
+      '',
+      '## Predicted blast radius',
+      '_What you expect to change + the risks (from /simulate-impact)._',
+      '',
+      '## Actual — fill on review',
+      '_What actually changed. Was the prediction right? Lessons for next time._',
+      '',
+    ].join('\n'), 'utf-8');
+    return rel;
+  } catch {
+    return null;
+  }
+}
+
+main().catch((err) => {
+  console.error('❌ mark-simulation failed:', err);
+  process.exit(1);
+});

package/templates/contextkit/tools/scripts/media-gen.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+/**
+ * /media-gen — CLI entry for the media-provider adapters (ADR-0024).
+ *
+ *   node contextkit/tools/scripts/media-gen.mjs image --prompt "..." --out path.png
+ *   node contextkit/tools/scripts/media-gen.mjs video --prompt "..." --out path.mp4
+ *   node contextkit/tools/scripts/media-gen.mjs image --prompt "..." --out path.png --dry-run
+ *
+ * Reads credentials from process.env (recommended: run via
+ * `node --env-file=contextkit/.env contextkit/tools/scripts/media-gen.mjs ...`
+ * on Node 20.6+). Refuses cleanly with NO_CREDENTIALS pointing at
+ * contextkit/.env.example when keys are absent.
+ *
+ * Defensive (rule 2). Zero deps.
+ */
+import { readdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { validateAdapter, MediaProviderError, MEDIA_ERROR_CODES, readCostCapUsd } from '../../runtime/providers/media/_adapter.mjs';
+
+const ADAPTERS_DIR = resolve(fileURLToPath(import.meta.url), '..', '..', '..', 'runtime', 'providers', 'media');
+
+const help = `Usage:
+  media-gen.mjs <image|video> --prompt "..." --out PATH [options]
+
+Common options:
+  --prompt "..."         what to generate (required)
+  --out PATH             where to write the file (required unless --dry-run)
+  --provider ID          force a specific adapter id (e.g. nano-banana, veo)
+  --aspect-ratio R       16:9 | 9:16 | 1:1 | 3:4 | 4:3 (provider-dependent)
+  --duration N           seconds (video only; default 8)
+  --model ID             override the adapter's default model
+  --sample-count N       image only; 1..4 (only the first is written)
+  --dry-run              show what would be called; make no network request
+  --help                 this message
+
+Env:
+  GOOGLE_AI_API_KEY              required for nano-banana + veo
+  CONTEXTDEVKIT_MEDIA_MAX_USD       optional per-process spend cap (USD)
+
+See contextkit/.env.example for the template.
+`;
+
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--dry-run') args.dryRun = true;
+    else if (a === '--help' || a === '-h') args.help = true;
+    else if (a.startsWith('--')) {
+      const name = a.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith('--')) { args[camel(name)] = next; i++; }
+      else args[camel(name)] = true;
+    } else {
+      args._.push(a);
+    }
+  }
+  return args;
+}
+const camel = (s) => s.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+
+async function loadAdapters() {
+  const files = readdirSync(ADAPTERS_DIR)
+    .filter((f) => f.endsWith('.mjs') && !f.startsWith('_'));
+  const out = [];
+  for (const file of files) {
+    const url = pathToFileURL(resolve(ADAPTERS_DIR, file)).href;
+    const mod = await import(url);
+    const verdict = validateAdapter(mod);
+    if (verdict.ok) out.push(mod);
+    else process.stderr.write(`media-gen: skipping ${file} — invalid adapter: ${verdict.reasons.join('; ')}\n`);
+  }
+  return out;
+}
+
+function pickAdapter(adapters, args) {
+  const kind = args._[0]; // 'image' | 'video'
+  if (!kind || (kind !== 'image' && kind !== 'video')) {
+    throw new Error(`first positional arg must be "image" or "video"; got: ${kind || '(nothing)'}`);
+  }
+  const wantId = args.provider;
+  const pool = adapters.filter((a) => a.kind === kind);
+  if (!pool.length) throw new Error(`no media adapter of kind="${kind}" is installed`);
+  if (wantId) {
+    const hit = pool.find((a) => a.id === wantId);
+    if (!hit) throw new Error(`no adapter with id="${wantId}" of kind="${kind}". Available: ${pool.map((a) => a.id).join(', ')}`);
+    return hit;
+  }
+  return pool[0];
+}
+
+function buildOptions(args) {
+  const o = {};
+  if (args.aspectRatio) o.aspectRatio = args.aspectRatio;
+  if (args.model) o.model = args.model;
+  if (args.duration) o.durationSeconds = Number(args.duration);
+  if (args.sampleCount) o.sampleCount = Number(args.sampleCount);
+  return o;
+}
+
+const isMain = (() => {
+  try {
+    const here = new URL(import.meta.url).pathname.toLowerCase();
+    const entry = process.argv[1]
+      ? new URL('file://' + process.argv[1].replace(/\\/g, '/')).pathname.toLowerCase()
+      : '';
+    return here === entry;
+  } catch { return false; }
+})();
+
+if (isMain) {
+  (async () => {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help || process.argv.length <= 2) {
+      process.stdout.write(help);
+      process.exit(0);
+    }
+    const adapters = await loadAdapters();
+    let adapter;
+    try { adapter = pickAdapter(adapters, args); }
+    catch (err) { process.stderr.write(`media-gen: ${err.message}\n`); process.exit(2); }
+
+    if (!args.prompt) { process.stderr.write('media-gen: --prompt is required\n'); process.exit(2); }
+    if (!args.out && !args.dryRun) { process.stderr.write('media-gen: --out PATH is required (or pass --dry-run)\n'); process.exit(2); }
+
+    const options = buildOptions(args);
+    const cap = readCostCapUsd();
+    const capLine = cap !== null ? ` · cost cap $${cap.toFixed(2)}` : '';
+
+    if (args.dryRun) {
+      process.stdout.write(`🎬 dry-run · ${adapter.id} (${adapter.kind})${capLine}\n`);
+      process.stdout.write(`   prompt: ${args.prompt}\n`);
+      process.stdout.write(`   out:    ${args.out || '(none)'}\n`);
+      process.stdout.write(`   options: ${JSON.stringify(options)}\n`);
+      process.stdout.write(`   env required: ${adapter.requiredEnv.join(', ')}${adapter.requiredEnv.every((n) => process.env[n]) ? ' ✓ set' : ' ✗ missing'}\n`);
+      process.exit(0);
+    }
+
+    try {
+      const r = await adapter.generate({ prompt: args.prompt, outPath: resolve(args.out), options });
+      process.stdout.write(`✅ ${adapter.id}: wrote ${r.outPath}\n`);
+      process.stdout.write(`   duration: ${r.durationMs} ms · est. cost: $${r.costEstimateUsd.toFixed(2)}${r.providerRequestId ? ` · req: ${r.providerRequestId}` : ''}\n`);
+      process.exit(0);
+    } catch (err) {
+      if (err instanceof MediaProviderError) {
+        process.stderr.write(`✗ ${err.code}: ${err.message}\n`);
+        process.exit(err.code === MEDIA_ERROR_CODES.NO_CREDENTIALS ? 3 : 1);
+      }
+      process.stderr.write(`media-gen: ${err.message}\n`);
+      process.exit(1);
+    }
+  })();
+}

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

@@ -0,0 +1,74 @@
+/**
+ * DevPipeline board rendering — turns the task list into `devpipeline.md`.
+ *
+ * Pure (takes the task array), so `pipeline.mjs` (the CLI) stays lean. Shows the
+ * WSJF priority + SLA, and flags overdue items (⏰).
+ */
+import { isOverdue } from './pipeline-prioritize.mjs';
+import { blockedBy } from './pipeline-validate.mjs';
+
+function table(tasks, allTasks) {
+  if (tasks.length === 0) return '_(empty)_\n';
+  const rows = ['| ID | Pri | WSJF | Type | Cx | Title | SLA | Roadmap |', '| --- | --- | --- | --- | --- | --- | --- | --- |'];
+  for (const t of tasks) {
+    const sla = t.sla ? (isOverdue(t) ? `⏰ ${t.sla}` : t.sla) : '—';
+    const cx = t.complexity || '—';
+    const n = blockedBy(t, allTasks);
+    const title = n > 0 ? `${t.title} ↘ blocked by ${n}` : t.title;
+    rows.push(`| ${t.id} | ${t.priority} | ${t.wsjf || '—'} | ${t.type} | ${cx} | ${title} | ${sla} | ${t.roadmap || '—'} |`);
+  }
+  return rows.join('\n') + '\n';
+}
+
+/** Full `devpipeline.md` markdown from the task list. */
+export function renderBoard(tasks) {
+  const by = (s) => tasks.filter((t) => t.stage === s);
+  const overdue = tasks.filter(isOverdue);
+  const out = [];
+  out.push('# DevPipeline — execution board');
+  out.push('');
+  out.push('> ⚠️  **AUTO-GENERATED** by `pipeline.mjs sync` (also on pre-commit). Do not hand-edit.');
+  out.push('> Product/business plan is `contextkit/memory/roadmap.md`. THIS is execution control:');
+  out.push('> bugs / increments / chores with **WSJF** priority + **SLA** (⏰ = overdue).');
+  out.push('');
+  out.push(`Backlog **${by('backlog').length}** · Working **${by('working').length}** · Testing **${by('testing').length}** · Concluded **${by('conclusion').length}** · ⏰ Overdue **${overdue.length}**`);
+  out.push('');
+  out.push('## 🔵 Working (active, owned by a session)');
+  out.push('');
+  out.push(table(by('working'), tasks));
+  out.push('## 🟡 In testing (code written, awaiting QA)');
+  out.push('');
+  out.push(table(by('testing'), tasks));
+  out.push('## 📋 Backlog (by priority)');
+  out.push('');
+  out.push(table(by('backlog'), tasks));
+  out.push('## ✅ Concluded (recent)');
+  out.push('');
+  out.push(table(by('conclusion').slice(-15), tasks));
+  return out.join('\n');
+}
+
+const SEV_ORDER = ['S1', 'S2', 'S3', 'S4', ''];
+const SEV_LABEL = { S1: 'S1 · Critical', S2: 'S2 · High', S3: 'S3 · Medium', S4: 'S4 · Low', '': 'Unclassified' };
+
+/** Known-bugs map: every `type: bug` task, grouped by severity, open vs resolved. */
+export function renderKnownBugs(tasks) {
+  const bugs = tasks.filter((t) => t.type === 'bug');
+  const out = ['# Known Bugs — map', ''];
+  out.push('> ⚠️ AUTO-GENERATED by `pipeline.mjs sync`. The bug registry, grouped by severity.');
+  out.push(`> ${bugs.length} known · ${bugs.filter((b) => b.stage !== 'conclusion').length} open · ${bugs.filter(isOverdue).length} ⏰ overdue`);
+  out.push('');
+  if (bugs.length === 0) return out.concat(['✅ No bugs on record.', '']).join('\n');
+  for (const sev of SEV_ORDER) {
+    const inSev = bugs.filter((b) => (b.severity || '') === sev);
+    if (inSev.length === 0) continue;
+    out.push(`## ${SEV_LABEL[sev]} (${inSev.length})`, '', '| ID | Status | Bug type | Title | SLA |', '| --- | --- | --- | --- | --- |');
+    for (const b of inSev) {
+      const status = b.stage === 'conclusion' ? '✅ resolved' : b.stage === 'testing' ? '🟡 testing' : b.stage === 'working' ? '🔵 working' : '📋 open';
+      const sla = b.sla ? (isOverdue(b) ? `⏰ ${b.sla}` : b.sla) : '—';
+      out.push(`| ${b.id} | ${status} | ${b.bugType || '—'} | ${b.title} | ${sla} |`);
+    }
+    out.push('');
+  }
+  return out.join('\n');
+}

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

@@ -0,0 +1,68 @@
+/**
+ * DevPipeline prioritization — WSJF (SAFe) + bug severity (S1–S4) + SLA.
+ *
+ * Pure functions over plain numbers/strings, zero deps. The bands / SLA / bug
+ * taxonomy can be overridden in `contextkit/config.json` → `pipeline.*`; these are
+ * the defaults the CLI falls back to.
+ *
+ * Model: every task lands on a priority **P0–P3**, derived from one of —
+ *   • WSJF score (value items)   → `wsjfToPriority`
+ *   • bug severity S1–S4 (bugs)  → `bugSeverityToPriority`
+ *   • scanner severity 1–5       → `severityToPriority`
+ * — and the **SLA due date** follows from the priority (`slaDue`).
+ */
+export const DEFAULTS = {
+  wsjfBands: { p0: 8, p1: 5, p2: 2 }, // WSJF score ≥ → priority
+  severityPriority: { S1: 'P0', S2: 'P1', S3: 'P2', S4: 'P3' }, // ITIL bug severity
+  slaDays: { P0: 1, P1: 3, P2: 14, P3: 60 }, // resolution target per priority
+  bugTypes: ['functional', 'regression', 'security', 'performance', 'data', 'integration', 'ui', 'build', 'flaky', 'other'],
+  workingStaleAfterMinutes: 90, // task auto-evicts from working/ if owning session is silent past this (ADR-0015 §B)
+};
+
+function num(x) {
+  const n = Number(x);
+  return Number.isFinite(n) ? n : 0;
+}
+
+/** WSJF (SAFe) = Cost of Delay ÷ Job Size. Inputs 1–10; returns a rounded score. */
+export function wsjfScore({ userValue = 0, timeCriticality = 0, riskReduction = 0, jobSize = 1 }) {
+  const cod = num(userValue) + num(timeCriticality) + num(riskReduction);
+  return Math.round((cod / Math.max(num(jobSize) || 1, 1)) * 10) / 10;
+}
+
+/** WSJF score → priority band. */
+export function wsjfToPriority(score, bands = DEFAULTS.wsjfBands) {
+  const s = num(score);
+  if (s >= bands.p0) return 'P0';
+  if (s >= bands.p1) return 'P1';
+  if (s >= bands.p2) return 'P2';
+  return 'P3';
+}
+
+/** Scanner numeric severity (1–5, 5 = worst) → priority. Debt caps at P1. */
+export function severityToPriority(sev) {
+  const n = num(sev);
+  if (n >= 4) return 'P1';
+  if (n >= 3) return 'P2';
+  return 'P3';
+}
+
+/** Bug severity label (S1–S4, S1 = critical) → priority. */
+export function bugSeverityToPriority(sev, map = DEFAULTS.severityPriority) {
+  return map[String(sev || '').toUpperCase()] || 'P2';
+}
+
+/** Resolution due date = created + SLA days for the priority (ISO yyyy-mm-dd). */
+export function slaDue(priority, createdISO, slaDays = DEFAULTS.slaDays) {
+  const days = slaDays[priority] ?? 30;
+  const base = createdISO ? new Date(createdISO) : new Date();
+  if (Number.isNaN(base.getTime())) return '';
+  return new Date(base.getTime() + days * 86400000).toISOString().slice(0, 10);
+}
+
+/** True when a not-yet-done task is past its SLA date. */
+export function isOverdue(task) {
+  if (!task || !task.sla || task.stage === 'conclusion') return false;
+  const due = new Date(task.sla);
+  return !Number.isNaN(due.getTime()) && due < new Date();
+}

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

@@ -0,0 +1,99 @@
+/**
+ * Session-aware DevPipeline transitions — `start` / `stop`.
+ *
+ * Separates a distinct responsibility from `pipeline.mjs` (pure CRUD on task
+ * files): these two transitions couple a task to a **session** via the
+ * workspace record (`claim.mjs`), and are the only places where a task move
+ * also writes session-level state. The CLI dispatch in `pipeline.mjs`
+ * delegates here.
+ *
+ * Cohesion: both halves share the same `findTaskFile` helper + the same
+ * stage-transition shape (rename + status rewrite + sync). Keeping them in one
+ * file makes start/stop symmetrical and lets the next maintainer read the full
+ * lifecycle in one place. See [ADR-0015 §B](../../memory/decisions/0015-pipeline-dsl-working-stage-and-multi-session-work-claims.md).
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync, renameSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { writeFileAtomicSync } from '../../runtime/hooks/safe-io.mjs';
+import { readState, writeState } from '../../runtime/state/state-io.mjs';
+import { attachTask, detachTask } from './claim.mjs';
+
+function gitOut(args, cwd, fallback) {
+  try {
+    return execFileSync('git', args, { cwd, encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim() || fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Resolves a task id (with or without zero-padding) to its current stage + file
+ * path. Returns `null` when the task isn't found — caller decides how to fail.
+ *
+ * @param {string} pipeDir — repo-relative pipeline dir (`contextkit/pipeline/`)
+ * @param {string} rawId
+ * @returns {{ stage: string, file: string } | null}
+ */
+function findTaskFile(pipeDir, rawId) {
+  const id = String(rawId).padStart(3, '0');
+  for (const stage of ['backlog', 'working', 'testing', 'conclusion']) {
+    const dir = resolve(pipeDir, stage);
+    if (!existsSync(dir)) continue;
+    const file = readdirSync(dir).find((f) => f.startsWith(`${id}-`) && f.endsWith('.md'));
+    if (file) return { stage, file };
+  }
+  return null;
+}
+
+function moveStage(pipeDir, from, to, file, statusValue) {
+  const fromPath = resolve(pipeDir, from, file);
+  const toPath = resolve(pipeDir, to, file);
+  const text = readFileSync(fromPath, 'utf-8').replace(/^(status:).*$/m, `status: ${statusValue}`);
+  writeFileAtomicSync(fromPath, text);
+  renameSync(fromPath, toPath);
+}
+
+/**
+ * `/pipeline start <id>` — moves a backlog task to `working/` AND attaches it
+ * to the current session's workspace record. Refuses when the task isn't in
+ * `backlog/` so a working/testing task can't be silently re-stamped.
+ *
+ * @param {string} pipeDir
+ * @param {string} rawId
+ * @param {(all: Array<object>) => void} sync — caller's sync function (renders board)
+ */
+export async function startTask(pipeDir, rawId, sync) {
+  const found = findTaskFile(pipeDir, rawId);
+  if (!found) throw new Error(`No task with id ${rawId}.`);
+  if (found.stage !== 'backlog') throw new Error(`Task ${rawId} is in '${found.stage}', not backlog — refusing to start.`);
+  moveStage(pipeDir, 'backlog', 'working', found.file, 'working');
+  sync();
+  await attachTask(rawId);
+  const id = String(rawId).padStart(3, '0');
+  // ADR-0015 §C — stamp the canonical state.json substrate.
+  try {
+    const cwd = pipeDir.split(/[\\/]+contextkit[\\/]+/)[0] || process.cwd();
+    writeState(pipeDir, id, { kind: 'task', status: 'working', branch: gitOut(['symbolic-ref', '--short', 'HEAD'], cwd, null), ownerUser: gitOut(['config', 'user.name'], cwd, null), endedAt: null });
+  } catch { /* best-effort: state.json is observability, not the source of truth */ }
+  return { id, stage: 'working' };
+}
+
+/**
+ * `/pipeline stop <id>` — moves a `working/` task BACK to `backlog/` (NOT
+ * testing/ — testing/ is "code done, awaiting QA", reached via explicit `move`)
+ * and detaches it from the session. Mirror of start.
+ */
+export async function stopTask(pipeDir, rawId, sync) {
+  const found = findTaskFile(pipeDir, rawId);
+  if (!found) throw new Error(`No task with id ${rawId}.`);
+  if (found.stage !== 'working') throw new Error(`Task ${rawId} is in '${found.stage}', not working — nothing to stop.`);
+  moveStage(pipeDir, 'working', 'backlog', found.file, 'backlog');
+  sync();
+  await detachTask(rawId);
+  const id = String(rawId).padStart(3, '0');
+  try {
+    if (readState(pipeDir, id)) writeState(pipeDir, id, { status: 'backlog', endedAt: Date.now() });
+  } catch { /* best-effort */ }
+  return { id, stage: 'backlog' };
+}