@hegemonart/get-design-done 1.27.5 → 1.27.7

package/scripts/lib/install/mcp-register.d.cts

@@ -0,0 +1,64 @@
+// scripts/lib/install/mcp-register.d.cts
+// ---------------------------------------------------------------------------
+// Plan 27.7-04 — TypeScript ambient declarations for the mcp-register lib.
+// Sibling .d.cts kept in sync with mcp-register.cjs (Phase 27.6 lesson —
+// precautionary for TS consumers).
+
+import type { spawnSync } from 'node:child_process';
+
+export interface Harness {
+  readonly binary: string;
+  readonly addArgs: readonly string[];
+  readonly listArgs: readonly string[];
+  readonly listMatchPattern: RegExp;
+}
+
+export const HARNESSES: Readonly<Record<'claude' | 'codex', Harness>>;
+export const MCP_NAME: string;
+
+export type HarnessId = 'claude' | 'codex';
+export type RegisterMode = 'register' | 'unregister' | 'detect';
+
+export interface RegisterMcpResult {
+  harness: HarnessId;
+  action: RegisterMode;
+  detected: boolean;
+  command: string | null;
+  applied: boolean;
+  idempotent_skip: boolean;
+  notice?: string;
+  stdout?: string;
+  stderr?: string;
+  exit_code?: number | null;
+  dry_run?: boolean;
+}
+
+export interface HarnessDetectEntry {
+  harness: HarnessId;
+  present: boolean;
+  registered: boolean | undefined;
+}
+
+export interface DetectResult {
+  harnesses: HarnessDetectEntry[];
+  summary: string;
+}
+
+export type SpawnFn = typeof spawnSync;
+
+export interface RegisterMcpOptions {
+  harness: HarnessId;
+  mode?: RegisterMode;
+  dryRun?: boolean;
+  spawnFn?: SpawnFn;
+}
+
+export interface DetectMcpRegistrationOptions {
+  spawnFn?: SpawnFn;
+}
+
+export function registerMcp(opts: RegisterMcpOptions): RegisterMcpResult;
+export function detectMcpRegistration(opts?: DetectMcpRegistrationOptions): DetectResult;
+export function detectHarnessPresent(harness: HarnessId, spawnFn?: SpawnFn): boolean;
+export function isAlreadyRegistered(harness: HarnessId, spawnFn?: SpawnFn): boolean;
+export function buildHarnessCommand(harness: HarnessId, mode?: RegisterMode): { binary: string; args: string[] };

package/scripts/lib/intel-store/index.cjs

@@ -0,0 +1,55 @@
+'use strict';
+// scripts/lib/intel-store/index.cjs — Plan 27.7-02
+//
+// Slice reader over <rootDir>/.design/intel/<slice_id>.json. Different
+// surface from scripts/lib/design-search.cjs (which does cross-cycle
+// FTS/grep recall) — see CONTEXT.md Warning #7.
+//
+// Surface:
+//   class IntelNotFoundError extends Error    — code='directory_not_found'
+//   async readSlice(rootDir, sliceId)         — parsed slice | null
+//   listSlices(rootDir)                       — string[] of slice ids
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+class IntelNotFoundError extends Error {
+  constructor(dir) {
+    super('source directory not found: ' + dir);
+    this.name = 'IntelNotFoundError';
+    this.code = 'directory_not_found';
+    this.dir = dir;
+  }
+}
+
+/** Read slice <rootDir>/.design/intel/<sliceId>.json. Returns parsed
+ *  JSON or `null` if the slice file is missing. Throws
+ *  IntelNotFoundError when the intel directory itself is absent. */
+async function readSlice(rootDir, sliceId) {
+  const dir = path.join(rootDir, '.design', 'intel');
+  if (!fs.existsSync(dir)) {
+    throw new IntelNotFoundError(dir);
+  }
+  const file = path.join(dir, sliceId + '.json');
+  if (!fs.existsSync(file)) return null;
+  const body = await fs.promises.readFile(file, 'utf8');
+  return JSON.parse(body);
+}
+
+/** List slice ids (file basenames without extension) under .design/intel/.
+ *  Throws IntelNotFoundError when the directory is absent. */
+function listSlices(rootDir) {
+  const dir = path.join(rootDir, '.design', 'intel');
+  if (!fs.existsSync(dir)) {
+    throw new IntelNotFoundError(dir);
+  }
+  const entries = fs.readdirSync(dir);
+  const ids = [];
+  for (const name of entries) {
+    if (!name.endsWith('.json')) continue;
+    ids.push(name.slice(0, -'.json'.length));
+  }
+  return ids;
+}
+
+module.exports = { readSlice, listSlices, IntelNotFoundError };

package/scripts/lib/intel-store/index.d.cts

@@ -0,0 +1,11 @@
+// scripts/lib/intel-store/index.d.cts — TypeScript ambient declarations
+// for the intel-store CJS module. Plan 27.7-02.
+
+export class IntelNotFoundError extends Error {
+  code: 'directory_not_found';
+  dir: string;
+  constructor(dir: string);
+}
+
+export function readSlice(rootDir: string, sliceId: string): Promise<unknown | null>;
+export function listSlices(rootDir: string): string[];

package/scripts/lib/mcp-tools-lint/index.cjs

@@ -0,0 +1,216 @@
+'use strict';
+// scripts/lib/mcp-tools-lint/index.cjs
+// ---------------------------------------------------------------------------
+// Plan 27.7-03 — static lint for the gdd-mcp tools directory.
+//
+// 4 invariants enforced (origin: Phase 27.7 CONTEXT decisions):
+//
+//   forbid-fs-path (D-06):  No direct `node:fs`/`node:path` (or bare `fs`/
+//                           `path`) imports inside individual tool .ts
+//                           files. Tools must be thin wrappers — all
+//                           filesystem I/O routes through scripts/lib/*
+//                           helpers (gdd-state, intel-store, etc.). The
+//                           `index.ts` and `shared.ts` siblings ARE
+//                           infrastructure and are exempt.
+//
+//   max-loc (D-06):         Each tool .ts file ≤ 30 non-blank-non-comment
+//                           LOC. Exempt: index.ts, shared.ts.
+//
+//   no-write-names (D-04):  Hard-block every write-verb tool name. A tool
+//                           name matching /_(create|update|delete|append|
+//                           clear|write|set)(_|$)/ is rejected. The MCP
+//                           server is read-only by design.
+//
+//   tool-count-cap (D-03):  ≤ 12 files matching `gdd_*.ts` glob in the
+//                           tools directory. Hard cap. Adding a 13th tool
+//                           requires re-scoping in a new plan.
+//
+// Public API:
+//   lintMcpToolsDir({dir, maxLoc?, toolCap?, exemptions?}) →
+//     { violations: LintViolation[], summary: { files_scanned, violations_count } }
+//
+// Consumed by tests/gdd-mcp-tools-lint.test.cjs and
+// tests/phase-27-7-baseline.test.cjs (Plan 27.7-07).
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const DEFAULT_EXEMPTIONS = new Set(['index.ts', 'shared.ts']);
+const DEFAULT_MAX_LOC = 30;
+const DEFAULT_TOOL_CAP = 12;
+const TOOL_FILE_GLOB = /^gdd_[a-z0-9_]+\.ts$/;
+
+const FORBIDDEN_IMPORT_PATTERNS = Object.freeze([
+  /from\s+['"]node:fs['"]/,
+  /from\s+['"]node:fs\/promises['"]/,
+  /from\s+['"]node:path['"]/,
+  /from\s+['"]fs['"]/,
+  /from\s+['"]path['"]/,
+  /require\s*\(\s*['"]node:fs['"]\s*\)/,
+  /require\s*\(\s*['"]node:fs\/promises['"]\s*\)/,
+  /require\s*\(\s*['"]fs['"]\s*\)/,
+  /require\s*\(\s*['"]node:path['"]\s*\)/,
+  /require\s*\(\s*['"]path['"]\s*\)/,
+]);
+
+// Write-verb pattern: matches when the verb is preceded by `_` and either
+// followed by `_` or end-of-string. e.g. `gdd_decision_append` matches;
+// `gdd_appendix_list` does NOT (the verb must be the trailing token of a
+// `_`-separated name).
+const WRITE_NAME_PATTERN = /_(create|update|delete|append|clear|write|set)(?:_|$)/;
+
+const RULES = Object.freeze([
+  'forbid-fs-path',
+  'max-loc',
+  'no-write-names',
+  'tool-count-cap',
+]);
+
+/**
+ * Count non-blank-non-comment lines.
+ * - Blank lines (whitespace-only) → excluded.
+ * - Lines whose first non-whitespace char is `//` (line comment) → excluded.
+ * - Lines starting with `/*` or `*` (block comment opener/continuation) → excluded.
+ */
+function countLoc(text) {
+  return text.split('\n').filter((line) => {
+    const t = line.trim();
+    if (t.length === 0) return false;
+    if (t.startsWith('//')) return false;
+    if (t.startsWith('/*')) return false;
+    if (t.startsWith('*')) return false;
+    return true;
+  }).length;
+}
+
+/**
+ * Scan source text line-by-line for the FORBIDDEN_IMPORT_PATTERNS.
+ * Returns [{rule, line, message}, …] (file is filled by the caller).
+ */
+function scanForbiddenImports(text) {
+  const violations = [];
+  const lines = text.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    for (const re of FORBIDDEN_IMPORT_PATTERNS) {
+      const m = line.match(re);
+      if (m) {
+        violations.push({
+          rule: 'forbid-fs-path',
+          line: i + 1,
+          message: 'forbidden import: ' + m[0],
+        });
+        break; // one violation per line is enough.
+      }
+    }
+  }
+  return violations;
+}
+
+/**
+ * Extract the `export const name = '…'` value. Tolerates `"` or `'` quotes
+ * and arbitrary whitespace. Returns {name, line} or null.
+ */
+function extractToolName(text) {
+  const lines = text.split('\n');
+  const re = /export\s+const\s+name\s*(?::\s*[A-Za-z<>{}\s,|]+)?\s*=\s*['"]([^'"]+)['"]/;
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(re);
+    if (m) return { name: m[1], line: i + 1 };
+  }
+  return null;
+}
+
+/**
+ * Main entry point. Scans `dir` for *.ts files, applies the 4 rules,
+ * and returns a structured result.
+ *
+ * @param {{dir: string, maxLoc?: number, toolCap?: number, exemptions?: Set<string>}} opts
+ * @returns {{violations: Array<{file: string, rule: string, line: number, message: string}>, summary: {files_scanned: number, violations_count: number}}}
+ */
+function lintMcpToolsDir(opts) {
+  if (!opts || typeof opts.dir !== 'string' || opts.dir.length === 0) {
+    throw new Error('lintMcpToolsDir: opts.dir is required');
+  }
+  const dir = opts.dir;
+  const maxLoc = typeof opts.maxLoc === 'number' ? opts.maxLoc : DEFAULT_MAX_LOC;
+  const toolCap =
+    typeof opts.toolCap === 'number' ? opts.toolCap : DEFAULT_TOOL_CAP;
+  const exemptions =
+    opts.exemptions instanceof Set ? opts.exemptions : DEFAULT_EXEMPTIONS;
+
+  const violations = [];
+
+  const entries = fs.readdirSync(dir);
+  const tsFiles = entries.filter((e) => e.endsWith('.ts'));
+
+  // Rule D — tool-count-cap (matches `gdd_*.ts` files only; index/shared
+  // never count toward the cap).
+  const toolFiles = entries.filter((e) => TOOL_FILE_GLOB.test(e));
+  if (toolFiles.length > toolCap) {
+    violations.push({
+      file: dir,
+      rule: 'tool-count-cap',
+      line: 0,
+      message: 'count=' + toolFiles.length + ' > cap=' + toolCap,
+    });
+  }
+
+  // Rules A, B, C — per-file scans.
+  for (const fname of tsFiles) {
+    const text = fs.readFileSync(path.join(dir, fname), 'utf8');
+    const isExempt = exemptions.has(fname);
+
+    // Rule A — forbid-fs-path (skip exemptions).
+    if (!isExempt) {
+      const fsViolations = scanForbiddenImports(text);
+      for (const v of fsViolations) {
+        violations.push({ file: fname, ...v });
+      }
+    }
+
+    // Rule B — max-loc (skip exemptions).
+    if (!isExempt) {
+      const loc = countLoc(text);
+      if (loc > maxLoc) {
+        violations.push({
+          file: fname,
+          rule: 'max-loc',
+          line: 0,
+          message: 'loc=' + loc + ' > max=' + maxLoc,
+        });
+      }
+    }
+
+    // Rule C — no-write-names. Applies to ALL ts files including
+    // exemptions (you should not even define a write-named symbol in
+    // index.ts or shared.ts — that would be a different bug).
+    const ext = extractToolName(text);
+    if (ext && WRITE_NAME_PATTERN.test(ext.name)) {
+      violations.push({
+        file: fname,
+        rule: 'no-write-names',
+        line: ext.line,
+        message: 'write tool name: ' + ext.name,
+      });
+    }
+  }
+
+  return {
+    violations,
+    summary: {
+      files_scanned: tsFiles.length,
+      violations_count: violations.length,
+    },
+  };
+}
+
+module.exports = {
+  lintMcpToolsDir,
+  RULES,
+  DEFAULT_EXEMPTIONS,
+  DEFAULT_MAX_LOC,
+  DEFAULT_TOOL_CAP,
+  FORBIDDEN_IMPORT_PATTERNS,
+  WRITE_NAME_PATTERN,
+};

package/scripts/lib/mcp-tools-lint/index.d.cts

@@ -0,0 +1,74 @@
+// scripts/lib/mcp-tools-lint/index.d.cts — ambient types for the .cjs lib.
+//
+// The runtime consumer is tests/gdd-mcp-tools-lint.test.cjs (CommonJS, so
+// types are not strictly required). This .d.cts ships the Phase 27.6
+// convention (any .cjs lib that may be imported from a .ts file gets a
+// sibling .d.cts) so that a future TypeScript consumer (e.g. a /lint:gdd
+// slash command) gets correct types without a follow-up patch.
+
+/** One detected lint failure. */
+export interface LintViolation {
+  /** Filename (relative to scan dir) or the dir itself for cap violations. */
+  file: string;
+  rule: 'forbid-fs-path' | 'max-loc' | 'no-write-names' | 'tool-count-cap';
+  /** 1-based source line; 0 for whole-file or whole-directory violations. */
+  line: number;
+  /** Human-readable diagnostic, e.g. `loc=42 > max=30`. */
+  message: string;
+}
+
+/** Counts for the scan as a whole. */
+export interface LintSummary {
+  files_scanned: number;
+  violations_count: number;
+}
+
+/** Return shape of {@link lintMcpToolsDir}. */
+export interface LintResult {
+  violations: LintViolation[];
+  summary: LintSummary;
+}
+
+/** Inputs to {@link lintMcpToolsDir}. Only `dir` is required. */
+export interface LintOptions {
+  /** Directory to scan. Tool files match `gdd_*.ts`. */
+  dir: string;
+  /** Max non-blank-non-comment LOC per tool file. Defaults to 30. */
+  maxLoc?: number;
+  /** Max number of `gdd_*.ts` tool files. Defaults to 12. */
+  toolCap?: number;
+  /**
+   * Filenames in `dir` exempt from forbid-fs-path + max-loc rules.
+   * Defaults to {'index.ts', 'shared.ts'}.
+   */
+  exemptions?: Set<string>;
+}
+
+/**
+ * Scan a directory of MCP tool .ts files and apply the 4 invariant rules.
+ * Pure-static — never executes the modules.
+ *
+ * - Rule A (`forbid-fs-path`): no fs/path imports in tool files (D-06).
+ * - Rule B (`max-loc`): each tool ≤ {@link LintOptions.maxLoc} LOC (D-06).
+ * - Rule C (`no-write-names`): no tool name with write-verb substring (D-04).
+ * - Rule D (`tool-count-cap`): ≤ {@link LintOptions.toolCap} tool files (D-03).
+ */
+export function lintMcpToolsDir(opts: LintOptions): LintResult;
+
+/** Ordered list of all rule names this module enforces. */
+export const RULES: readonly LintViolation['rule'][];
+
+/** Default exempt filenames (index.ts + shared.ts). */
+export const DEFAULT_EXEMPTIONS: Set<string>;
+
+/** Default value for the LOC ceiling. */
+export const DEFAULT_MAX_LOC: number;
+
+/** Default value for the tool-count cap. */
+export const DEFAULT_TOOL_CAP: number;
+
+/** The regexes Rule A scans for, line by line. */
+export const FORBIDDEN_IMPORT_PATTERNS: readonly RegExp[];
+
+/** The regex Rule C matches against the extracted `export const name`. */
+export const WRITE_NAME_PATTERN: RegExp;

package/scripts/lib/parallelism-engine/concurrency-tuner.cjs

@@ -0,0 +1,259 @@
+/**
+ * scripts/lib/parallelism-engine/concurrency-tuner.cjs — Plan 27.6-04
+ *
+ * Data-driven concurrency resolver per Phase 27.6 D-07. Reads the
+ * most-recent `parallelism.verdict` event from .design/telemetry/
+ * events.jsonl (Phase 22 stream) and computes:
+ *
+ *   resolveConcurrency = max(1, min(min(cpu-1, last_observed), ceiling))
+ *
+ * where:
+ *   cpu           = os.cpus().length (override via cpuCount opt)
+ *   last_observed = payload.observed_concurrency from the latest
+ *                   parallelism.verdict event (null if absent)
+ *   ceiling       = process.env.GDD_CONCURRENCY_CEILING (default 8)
+ *
+ * Hard ceiling of 8 prevents pathological process-spawn storms on
+ * high-core machines (D-07 wording: "Hard ceiling prevents pathological
+ * process-spawn storms").
+ *
+ * Public surface:
+ *   * resolveConcurrency({cpuCount?, lastObservedOptimum?, hardCeiling?,
+ *                        eventsPath?, baseDir?}) -> number  (>=1)
+ *   * readLastObservedOptimum({eventsPath?, baseDir?}) -> number|null
+ *   * emitParallelismVerdict({task_ids, verdict, reason,
+ *                            intended_concurrency?, observed_concurrency?,
+ *                            contention_detected?, wall_clock_ms?,
+ *                            sessionId?}) -> void
+ *   * DEFAULT_HARD_CEILING (=8)
+ *   * DEFAULT_EVENTS_PATH (='.design/telemetry/events.jsonl')
+ *
+ * The `parallelism.verdict` payload extension is purely additive
+ * (`intended_concurrency`, `observed_concurrency`, `contention_detected`,
+ * `wall_clock_ms` are all optional). Existing consumers that only read
+ * `{task_ids, verdict, reason}` keep working unchanged.
+ *
+ * No external deps. Lazy event-stream require for emit (best-effort
+ * telemetry — a failed event-stream load must not break the resolver).
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const DEFAULT_HARD_CEILING = 8;
+const DEFAULT_EVENTS_PATH = '.design/telemetry/events.jsonl';
+
+/**
+ * Lazy-require the event-stream module. Returns a no-op `appendEvent`
+ * when the module is unavailable so callers never have to wrap emit
+ * calls in try/catch themselves.
+ *
+ * @returns {(ev: object) => void}
+ */
+function getAppendEvent() {
+  try {
+    // Resolved relative to this file: scripts/lib/parallelism-engine/
+    // -> ../event-stream. The event-stream module is .ts; Node 22+
+    // with --experimental-strip-types (or Node 24 built-in TS) can
+    // require it. If require fails (e.g., older runtime, missing
+    // module), fall through to the no-op.
+    const m = require('../event-stream');
+    if (m && typeof m.appendEvent === 'function') return m.appendEvent;
+  } catch {
+    // Swallow — best-effort telemetry. Losing one verdict is
+    // acceptable; breaking concurrency resolution is not.
+  }
+  return function noopAppend(_ev) {
+    /* event-stream unavailable */
+  };
+}
+
+/**
+ * Resolve the hard ceiling. Operator override via GDD_CONCURRENCY_CEILING
+ * env var (parsed as integer) takes precedence; the explicit `override`
+ * argument wins over the env. Default is 8 (D-07).
+ *
+ * @param {number|undefined} override
+ * @returns {number}
+ */
+function resolveCeiling(override) {
+  if (typeof override === 'number' && override >= 1) return Math.floor(override);
+  const env = process.env.GDD_CONCURRENCY_CEILING;
+  if (typeof env === 'string' && env.length > 0) {
+    const parsed = parseInt(env, 10);
+    if (Number.isFinite(parsed) && parsed >= 1) return parsed;
+  }
+  return DEFAULT_HARD_CEILING;
+}
+
+/**
+ * Compose the JSONL events path. Relative paths are joined to baseDir
+ * when supplied; absolute paths are returned as-is.
+ *
+ * @param {{eventsPath?: string, baseDir?: string}} opts
+ * @returns {string}
+ */
+function resolvePath({ eventsPath, baseDir }) {
+  let p = typeof eventsPath === 'string' && eventsPath.length > 0
+    ? eventsPath
+    : DEFAULT_EVENTS_PATH;
+  if (baseDir && !path.isAbsolute(p)) p = path.join(baseDir, p);
+  return p;
+}
+
+/**
+ * Read .design/telemetry/events.jsonl and return the
+ * `observed_concurrency` from the MOST RECENT parallelism.verdict event
+ * (sequential read order). Tolerates malformed lines and absent file.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.eventsPath] override events.jsonl path
+ * @param {string} [opts.baseDir]    base for relative eventsPath
+ * @returns {number|null}
+ */
+function readLastObservedOptimum({ eventsPath, baseDir } = {} ) {
+  const target = resolvePath({ eventsPath, baseDir });
+  if (!fs.existsSync(target)) return null;
+  let body;
+  try {
+    body = fs.readFileSync(target, 'utf8');
+  } catch {
+    return null;
+  }
+  const lines = body.split(/\r?\n/);
+  let lastOptimum = null;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    try {
+      const ev = JSON.parse(trimmed);
+      if (
+        ev
+        && ev.type === 'parallelism.verdict'
+        && ev.payload
+        && typeof ev.payload.observed_concurrency === 'number'
+      ) {
+        lastOptimum = Math.floor(ev.payload.observed_concurrency);
+      }
+    } catch {
+      // Tolerate malformed line — JSONL is best-effort.
+    }
+  }
+  return lastOptimum;
+}
+
+/**
+ * Resolve the recommended concurrency per D-07.
+ *
+ *   1. base       = max(1, cpuCount - 1)         // never below 1
+ *   2. optimum    = lastObservedOptimum         // explicit override
+ *                   ?? readLastObservedOptimum() // or read from JSONL
+ *   3. candidate  = optimum > 0 ? min(base, optimum) : base
+ *   4. ceiling    = override ?? GDD_CONCURRENCY_CEILING ?? 8
+ *   5. return max(1, min(candidate, ceiling))
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.cpuCount]            override os.cpus().length
+ * @param {number|null} [opts.lastObservedOptimum] explicit override; null/undefined triggers JSONL read
+ * @param {number} [opts.hardCeiling]         override the env/default ceiling
+ * @param {string} [opts.eventsPath]          override events.jsonl path
+ * @param {string} [opts.baseDir]             base for relative eventsPath
+ * @returns {number} integer >= 1
+ */
+function resolveConcurrency({
+  cpuCount,
+  lastObservedOptimum,
+  hardCeiling,
+  eventsPath,
+  baseDir,
+} = {}) {
+  const cpu = typeof cpuCount === 'number' && cpuCount >= 1
+    ? Math.floor(cpuCount)
+    : os.cpus().length;
+  const base = Math.max(1, cpu - 1);
+  let optimum = lastObservedOptimum;
+  if (optimum === undefined || optimum === null) {
+    optimum = readLastObservedOptimum({ eventsPath, baseDir });
+  }
+  const candidate = typeof optimum === 'number' && optimum >= 1
+    ? Math.min(base, Math.floor(optimum))
+    : base;
+  const ceiling = resolveCeiling(hardCeiling);
+  return Math.max(1, Math.min(candidate, ceiling));
+}
+
+/**
+ * Emit a `parallelism.verdict` event with the Phase 27.6 superset
+ * payload. Existing fields ({task_ids, verdict, reason}) are always
+ * present; the new fields (intended_concurrency, observed_concurrency,
+ * contention_detected, wall_clock_ms) are appended only when supplied.
+ *
+ * Side effect: appendEvent({type: 'parallelism.verdict', ...}). When
+ * event-stream is unavailable, this is a no-op (lazy require fallback).
+ *
+ * @param {object} opts
+ * @param {string[]} opts.task_ids
+ * @param {'parallel'|'sequential'} opts.verdict
+ * @param {string}  opts.reason
+ * @param {number}  [opts.intended_concurrency]
+ * @param {number}  [opts.observed_concurrency]
+ * @param {boolean} [opts.contention_detected]
+ * @param {number}  [opts.wall_clock_ms]
+ * @param {string}  [opts.sessionId]
+ * @returns {void}
+ */
+function emitParallelismVerdict({
+  task_ids,
+  verdict,
+  reason,
+  intended_concurrency,
+  observed_concurrency,
+  contention_detected,
+  wall_clock_ms,
+  sessionId,
+} = {}) {
+  const append = getAppendEvent();
+  /** @type {Record<string, unknown>} */
+  const payload = {
+    task_ids: Array.isArray(task_ids) ? task_ids : [],
+    verdict: verdict === 'parallel' || verdict === 'sequential' ? verdict : 'sequential',
+    reason: typeof reason === 'string' ? reason : 'unspecified',
+  };
+  // Additive 27.6 fields — only include when set, to keep payloads
+  // compact and avoid noisy `undefined` keys on the wire.
+  if (typeof intended_concurrency === 'number') {
+    payload.intended_concurrency = intended_concurrency;
+  }
+  if (typeof observed_concurrency === 'number') {
+    payload.observed_concurrency = observed_concurrency;
+  }
+  if (typeof contention_detected === 'boolean') {
+    payload.contention_detected = contention_detected;
+  }
+  if (typeof wall_clock_ms === 'number') {
+    payload.wall_clock_ms = wall_clock_ms;
+  }
+  try {
+    append({
+      type: 'parallelism.verdict',
+      timestamp: new Date().toISOString(),
+      sessionId: typeof sessionId === 'string' && sessionId.length > 0
+        ? sessionId
+        : 'concurrency-tuner',
+      payload,
+    });
+  } catch {
+    // Best-effort telemetry. A failed write must never break the
+    // caller's wave-execution flow.
+  }
+}
+
+module.exports = {
+  resolveConcurrency,
+  readLastObservedOptimum,
+  emitParallelismVerdict,
+  DEFAULT_HARD_CEILING,
+  DEFAULT_EVENTS_PATH,
+};