@opengsd/gsd-core 1.2.0-rc.1

package/get-shit-done/bin/lib/milestone.cjs

@@ -0,0 +1,314 @@
+/**
+ * Milestone — Milestone and requirements lifecycle operations
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { escapeRegex, getMilestonePhaseFilter, extractOneLinerFromBody, output, error } = require('./core.cjs');
+const { platformWriteSync, platformEnsureDir } = require('./shell-command-projection.cjs');
+const { planningPaths } = require('./planning-workspace.cjs');
+const { extractFrontmatter } = require('./frontmatter.cjs');
+const { writeStateMd, stateReplaceFieldWithFallback } = require('./state.cjs');
+const { formatGsdSlash, resolveRuntime } = require('./runtime-slash.cjs');
+
+function cmdRequirementsMarkComplete(cwd, reqIdsRaw, raw) {
+  if (!reqIdsRaw || reqIdsRaw.length === 0) {
+    error('requirement IDs required. Usage: requirements mark-complete REQ-01,REQ-02 or REQ-01 REQ-02');
+  }
+
+  // Accept comma-separated, space-separated, or bracket-wrapped: [REQ-01, REQ-02]
+  const reqIds = reqIdsRaw
+    .join(' ')
+    .replace(/[\[\]]/g, '')
+    .split(/[,\s]+/)
+    .map(r => r.trim())
+    .filter(Boolean);
+
+  if (reqIds.length === 0) {
+    error('no valid requirement IDs found');
+  }
+
+  const reqPath = planningPaths(cwd).requirements;
+  if (!fs.existsSync(reqPath)) {
+    output({ updated: false, reason: 'REQUIREMENTS.md not found', ids: reqIds }, raw, 'no requirements file');
+    return;
+  }
+
+  let reqContent = fs.readFileSync(reqPath, 'utf-8');
+  const updated = [];
+  const alreadyComplete = [];
+  const notFound = [];
+
+  for (const reqId of reqIds) {
+    let found = false;
+    const reqEscaped = escapeRegex(reqId);
+
+    // Update checkbox: - [ ] **REQ-ID** → - [x] **REQ-ID**
+    // Use replace() directly and compare — avoids test()+replace() global regex
+    // lastIndex bug where test() advances state and replace() misses matches.
+    const checkboxPattern = new RegExp(`(-\\s*\\[)[ ](\\]\\s*\\*\\*${reqEscaped}\\*\\*)`, 'gi');
+    const afterCheckbox = reqContent.replace(checkboxPattern, '$1x$2');
+    if (afterCheckbox !== reqContent) {
+      reqContent = afterCheckbox;
+      found = true;
+    }
+
+    // Update traceability table: | REQ-ID | Phase N | Pending | → | REQ-ID | Phase N | Complete |
+    const tablePattern = new RegExp(`(\\|\\s*${reqEscaped}\\s*\\|[^|]+\\|)\\s*Pending\\s*(\\|)`, 'gi');
+    const afterTable = reqContent.replace(tablePattern, '$1 Complete $2');
+    if (afterTable !== reqContent) {
+      reqContent = afterTable;
+      found = true;
+    }
+
+    if (found) {
+      updated.push(reqId);
+    } else {
+      // Check if already complete before declaring not_found.
+      // Non-global flag is fine here — we only need to know if a match exists.
+      const doneCheckbox = new RegExp(`-\\s*\\[x\\]\\s*\\*\\*${reqEscaped}\\*\\*`, 'i');
+      const doneTable = new RegExp(`\\|\\s*${reqEscaped}\\s*\\|[^|]+\\|\\s*Complete\\s*\\|`, 'i');
+      if (doneCheckbox.test(reqContent) || doneTable.test(reqContent)) {
+        alreadyComplete.push(reqId);
+      } else {
+        notFound.push(reqId);
+      }
+    }
+  }
+
+  if (updated.length > 0) {
+    platformWriteSync(reqPath, reqContent);
+  }
+
+  output({
+    updated: updated.length > 0,
+    marked_complete: updated,
+    already_complete: alreadyComplete,
+    not_found: notFound,
+    total: reqIds.length,
+  }, raw, `${updated.length}/${reqIds.length} requirements marked complete`);
+}
+
+function cmdMilestoneComplete(cwd, version, options, raw) {
+  if (!version) {
+    error('version required for milestone complete (e.g., v1.0)');
+  }
+
+  const roadmapPath = planningPaths(cwd).roadmap;
+  const reqPath = planningPaths(cwd).requirements;
+  const statePath = planningPaths(cwd).state;
+  const milestonesPath = path.join(cwd, '.planning', 'MILESTONES.md');
+  const archiveDir = path.join(cwd, '.planning', 'milestones');
+  const phasesDir = planningPaths(cwd).phases;
+  const today = new Date().toISOString().split('T')[0];
+  const milestoneName = options.name || version;
+
+  // Ensure archive directory exists
+  platformEnsureDir(archiveDir);
+
+  // Scope stats and accomplishments to only the phases belonging to the
+  // current milestone's ROADMAP.  Uses the shared filter from core.cjs
+  // (same logic used by cmdPhasesList and other callers).
+  const isDirInMilestone = getMilestonePhaseFilter(cwd, version);
+  if (isDirInMilestone.missingExplicitVersion) {
+    error(`no phases found for milestone ${version} in ROADMAP.md`);
+  }
+
+  // Gather stats from phases (scoped to current milestone only)
+  let phaseCount = 0;
+  let totalPlans = 0;
+  let totalTasks = 0;
+  const accomplishments = [];
+
+  try {
+    const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+    const dirs = entries.filter(e => e.isDirectory()).map(e => e.name).sort();
+
+    for (const dir of dirs) {
+      if (!isDirInMilestone(dir)) continue;
+
+      phaseCount++;
+      const phaseFiles = fs.readdirSync(path.join(phasesDir, dir));
+      const plans = phaseFiles.filter(f => f.endsWith('-PLAN.md') || f === 'PLAN.md');
+      const summaries = phaseFiles.filter(f => f.endsWith('-SUMMARY.md') || f === 'SUMMARY.md');
+      totalPlans += plans.length;
+
+      // Extract one-liners from summaries
+      for (const s of summaries) {
+        try {
+          const content = fs.readFileSync(path.join(phasesDir, dir, s), 'utf-8');
+          const fm = extractFrontmatter(content);
+          const oneLiner = fm['one-liner'] || extractOneLinerFromBody(content);
+          if (oneLiner) {
+            accomplishments.push(oneLiner);
+          }
+          // Count tasks: prefer **Tasks:** N from Performance section,
+          // then <task XML tags, then ## Task N markdown headers
+          const tasksFieldMatch = content.match(/\*\*Tasks:\*\*\s*(\d+)/);
+          if (tasksFieldMatch) {
+            totalTasks += parseInt(tasksFieldMatch[1], 10);
+          } else {
+            const xmlTaskMatches = content.match(/<task[\s>]/gi) || [];
+            const mdTaskMatches = content.match(/##\s*Task\s*\d+/gi) || [];
+            totalTasks += xmlTaskMatches.length || mdTaskMatches.length;
+          }
+        } catch { /* intentionally empty */ }
+      }
+    }
+  } catch { /* intentionally empty */ }
+
+  // Archive ROADMAP.md
+  if (fs.existsSync(roadmapPath)) {
+    const roadmapContent = fs.readFileSync(roadmapPath, 'utf-8');
+    platformWriteSync(path.join(archiveDir, `${version}-ROADMAP.md`), roadmapContent);
+  }
+
+  // Archive REQUIREMENTS.md
+  if (fs.existsSync(reqPath)) {
+    const reqContent = fs.readFileSync(reqPath, 'utf-8');
+    const archiveHeader = `# Requirements Archive: ${version} ${milestoneName}\n\n**Archived:** ${today}\n**Status:** SHIPPED\n\nFor current requirements, see \`.planning/REQUIREMENTS.md\`.\n\n---\n\n`;
+    platformWriteSync(path.join(archiveDir, `${version}-REQUIREMENTS.md`), archiveHeader + reqContent);
+  }
+
+  // Archive audit file if exists
+  const auditFile = path.join(cwd, '.planning', `${version}-MILESTONE-AUDIT.md`);
+  if (fs.existsSync(auditFile)) {
+    fs.renameSync(auditFile, path.join(archiveDir, `${version}-MILESTONE-AUDIT.md`));
+  }
+
+  // Create/append MILESTONES.md entry
+  const accomplishmentsList = accomplishments.map(a => `- ${a}`).join('\n');
+  const milestoneEntry = `## ${version} ${milestoneName} (Shipped: ${today})\n\n**Phases completed:** ${phaseCount} phases, ${totalPlans} plans, ${totalTasks} tasks\n\n**Key accomplishments:**\n${accomplishmentsList || '- (none recorded)'}\n\n---\n\n`;
+
+  if (fs.existsSync(milestonesPath)) {
+    const existing = fs.readFileSync(milestonesPath, 'utf-8');
+    if (!existing.trim()) {
+      // Empty file — treat like new
+      platformWriteSync(milestonesPath, `# Milestones\n\n${milestoneEntry}`);
+    } else {
+      // Insert after the header line(s) for reverse chronological order (newest first)
+      const headerMatch = existing.match(/^(#{1,3}\s+[^\n]*\n\n?)/);
+      if (headerMatch) {
+        const header = headerMatch[1];
+        const rest = existing.slice(header.length);
+        platformWriteSync(milestonesPath, header + milestoneEntry + rest);
+      } else {
+        // No recognizable header — prepend the entry
+        platformWriteSync(milestonesPath, milestoneEntry + existing);
+      }
+    }
+  } else {
+    platformWriteSync(milestonesPath, `# Milestones\n\n${milestoneEntry}`);
+  }
+
+  // Update STATE.md — keep frontmatter/body semantically aligned after closure
+  if (fs.existsSync(statePath)) {
+    let stateContent = fs.readFileSync(statePath, 'utf-8');
+
+    stateContent = stateReplaceFieldWithFallback(stateContent, 'Status', null, `${version} milestone complete`);
+    stateContent = stateReplaceFieldWithFallback(stateContent, 'Last Activity', 'Last activity', today);
+    stateContent = stateReplaceFieldWithFallback(stateContent, 'Last Activity Description', null,
+      `${version} milestone completed and archived`);
+
+    // Reset Current Position narrative so resume/progress flows do not keep
+    // pointing at closed-phase execution instructions.
+    const positionPattern = /(##\s*Current Position\s*\n)([\s\S]*?)(?=\n##|$)/i;
+    const closedPositionBody =
+      `\nPhase: Milestone ${version} complete\n` +
+      `Plan: —\n` +
+      `Status: Awaiting next milestone\n` +
+      `Last activity: ${today} — Milestone ${version} completed and archived\n\n`;
+    if (positionPattern.test(stateContent)) {
+      stateContent = stateContent.replace(positionPattern, (_m, header) => `${header}${closedPositionBody}`);
+    } else {
+      stateContent = `${stateContent.trimEnd()}\n\n## Current Position\n${closedPositionBody}`;
+    }
+
+    // Normalize operator-next-step tails that can become stale after close.
+    const operatorPattern = /(##\s*Operator Next Steps\s*\n)([\s\S]*?)(?=\n##|$)/i;
+    if (operatorPattern.test(stateContent)) {
+      stateContent = stateContent.replace(
+        operatorPattern,
+        `$1\n- Start the next milestone with ${formatGsdSlash('new-milestone', resolveRuntime(cwd))}\n\n`,
+      );
+    } else {
+      stateContent = `${stateContent.trimEnd()}\n\n## Operator Next Steps\n\n- Start the next milestone with ${formatGsdSlash('new-milestone', resolveRuntime(cwd))}\n`;
+    }
+
+    writeStateMd(statePath, stateContent, cwd);
+  }
+
+  // Archive phase directories if requested
+  let phasesArchived = false;
+  if (options.archivePhases) {
+    try {
+      const phaseArchiveDir = path.join(archiveDir, `${version}-phases`);
+      platformEnsureDir(phaseArchiveDir);
+
+      const phaseEntries = fs.readdirSync(phasesDir, { withFileTypes: true });
+      const phaseDirNames = phaseEntries.filter(e => e.isDirectory()).map(e => e.name);
+      let archivedCount = 0;
+      for (const dir of phaseDirNames) {
+        if (!isDirInMilestone(dir)) continue;
+        fs.renameSync(path.join(phasesDir, dir), path.join(phaseArchiveDir, dir));
+        archivedCount++;
+      }
+      phasesArchived = archivedCount > 0;
+    } catch { /* intentionally empty */ }
+  }
+
+  const result = {
+    version,
+    name: milestoneName,
+    date: today,
+    phases: phaseCount,
+    plans: totalPlans,
+    tasks: totalTasks,
+    accomplishments,
+    archived: {
+      roadmap: fs.existsSync(path.join(archiveDir, `${version}-ROADMAP.md`)),
+      requirements: fs.existsSync(path.join(archiveDir, `${version}-REQUIREMENTS.md`)),
+      audit: fs.existsSync(path.join(archiveDir, `${version}-MILESTONE-AUDIT.md`)),
+      phases: phasesArchived,
+    },
+    milestones_updated: true,
+    state_updated: fs.existsSync(statePath),
+  };
+
+  output(result, raw);
+}
+
+function cmdPhasesClear(cwd, raw, args) {
+  const phasesDir = planningPaths(cwd).phases;
+  const confirm = Array.isArray(args) && args.includes('--confirm');
+  let cleared = 0;
+
+  if (fs.existsSync(phasesDir)) {
+    const entries = fs.readdirSync(phasesDir, { withFileTypes: true });
+    const dirs = entries.filter(e => e.isDirectory() && !/^999(?:\.|$)/.test(e.name));
+
+    if (dirs.length > 0 && !confirm) {
+      error(
+        `phases clear would delete ${dirs.length} phase director${dirs.length === 1 ? 'y' : 'ies'}. ` +
+        `Pass --confirm to proceed.`
+      );
+    }
+
+    try {
+      for (const entry of dirs) {
+        fs.rmSync(path.join(phasesDir, entry.name), { recursive: true, force: true });
+        cleared++;
+      }
+    } catch (e) {
+      error('Failed to clear phases directory: ' + e.message);
+    }
+  }
+
+  output({ cleared }, raw, `${cleared} phase director${cleared === 1 ? 'y' : 'ies'} cleared`);
+}
+
+module.exports = {
+  cmdRequirementsMarkComplete,
+  cmdMilestoneComplete,
+  cmdPhasesClear,
+};

package/get-shit-done/bin/lib/model-catalog.cjs

@@ -0,0 +1,212 @@
+'use strict';
+
+const path = require('node:path');
+
+// Resolve model-catalog.json via a prioritised candidate list so the module
+// works in every layout:
+//
+//   1. Co-located install path — get-shit-done/bin/shared/model-catalog.json
+//      Written by bin/install.js (#3288 fix). This is the canonical post-install
+//      location across all runtimes (Claude Code, Codex, OpenCode, etc.).
+//
+//   2. Source-repo dev path — sdk/shared/model-catalog.json
+//      Three levels up from bin/lib/: works when running directly from the
+//      open-gsd/gsd-core clone (the original path introduced by #3230).
+//
+//   3. GSD_MODEL_CATALOG env override — allows test harnesses and custom
+//      deployments to point at an arbitrary catalog file.
+//
+// Throws with a diagnostic message that lists all candidates when none resolve,
+// so MODULE_NOT_FOUND surfaces as a clear actionable error (PRED.k301).
+const _catalogCandidates = [
+  path.resolve(__dirname, '..', 'shared', 'model-catalog.json'),
+  path.resolve(__dirname, '..', '..', '..', 'sdk', 'shared', 'model-catalog.json'),
+  process.env.GSD_MODEL_CATALOG ? path.resolve(process.env.GSD_MODEL_CATALOG) : null,
+].filter(Boolean);
+
+let catalog = null;
+let _catalogLastErr = null;
+for (const _p of _catalogCandidates) {
+  try {
+    catalog = require(_p);
+    break;
+  } catch (e) {
+    // Only treat missing-file errors as recoverable — rethrow parse errors,
+    // permission errors, and any other real failures so they surface clearly
+    // instead of being silently swallowed (CR finding, PR #3293).
+    const isMissingCandidate =
+      (e && e.code === 'MODULE_NOT_FOUND' && String(e.message || '').includes(_p)) ||
+      (e && e.code === 'ENOENT');
+    if (!isMissingCandidate) throw e;
+    _catalogLastErr = e;
+  }
+}
+if (!catalog) {
+  throw new Error(
+    `model-catalog.json not found. Tried:\n${_catalogCandidates.map((p) => `  ${p}`).join('\n')}\nLast error: ${_catalogLastErr?.message}`
+  );
+}
+
+const VALID_PROFILES = [...catalog.profiles];
+const VALID_PHASE_TYPES = new Set(catalog.phaseTypes);
+const VALID_AGENT_TIERS = new Set(Object.keys(catalog.adaptiveTierMap));
+
+const MODEL_PROFILES = Object.fromEntries(
+  Object.entries(catalog.agents).map(([agent, meta]) => [agent, {
+    quality: meta.golden,
+    balanced: meta.balanced,
+    budget: meta.budget,
+    adaptive: catalog.adaptiveTierMap[meta.routingTier],
+  }])
+);
+
+const AGENT_TO_PHASE_TYPE = Object.fromEntries(
+  Object.entries(catalog.agents).map(([agent, meta]) => [agent, meta.phaseType])
+);
+
+const AGENT_DEFAULT_TIERS = Object.fromEntries(
+  Object.entries(catalog.agents).map(([agent, meta]) => [agent, meta.routingTier])
+);
+
+const MODEL_ALIAS_MAP = Object.fromEntries(
+  Object.entries(catalog.runtimeTierDefaults.claude).map(([tier, entry]) => [tier, entry?.model])
+);
+
+const RUNTIME_PROFILE_MAP = Object.fromEntries(
+  Object.entries(catalog.runtimeTierDefaults)
+    .map(([runtime, tiers]) => [
+      runtime,
+      Object.fromEntries(
+        Object.entries(tiers).filter(([, entry]) => entry).map(([tier, entry]) => [tier, entry])
+      ),
+    ])
+    .filter(([, tiers]) => Object.keys(tiers).length > 0)
+);
+
+const KNOWN_RUNTIMES = new Set(Object.keys(catalog.runtimeTierDefaults));
+const RUNTIMES_WITH_REASONING_EFFORT = new Set(
+  Object.entries(catalog.runtimeTierDefaults)
+    .filter(([, tiers]) => Object.values(tiers).some((entry) => entry && entry.reasoning_effort))
+    .map(([runtime]) => runtime)
+);
+
+function nextTier(currentTier) {
+  const order = ['light', 'standard', 'heavy'];
+  const idx = order.indexOf(String(currentTier));
+  if (idx === -1) return null;
+  return order[Math.min(idx + 1, order.length - 1)];
+}
+
+function formatAgentToModelMapAsTable(agentToModelMap) {
+  const agentWidth = Math.max('Agent'.length, ...Object.keys(agentToModelMap).map((a) => a.length));
+  const modelWidth = Math.max('Model'.length, ...Object.values(agentToModelMap).map((m) => m.length));
+  const sep = '─'.repeat(agentWidth + 2) + '┼' + '─'.repeat(modelWidth + 2);
+  const header = ` ${'Agent'.padEnd(agentWidth)} │ ${'Model'.padEnd(modelWidth)}`;
+  let out = `${header}\n${sep}\n`;
+  for (const [agent, model] of Object.entries(agentToModelMap)) {
+    out += ` ${agent.padEnd(agentWidth)} │ ${model.padEnd(modelWidth)}\n`;
+  }
+  return out;
+}
+
+function getAgentToModelMapForProfile(normalizedProfile) {
+  const profile = VALID_PROFILES.includes(normalizedProfile) ? normalizedProfile : 'balanced';
+  const out = {};
+  for (const [agent, profiles] of Object.entries(MODEL_PROFILES)) {
+    out[agent] = profile === 'inherit' ? 'inherit' : (profiles[profile] ?? profiles.balanced);
+  }
+  return out;
+}
+
+// ─── Effort rendering ────────────────────────────────────────────────────────
+//
+// Universal effort ladder: minimal < low < medium < high < xhigh < max
+//
+// Each runtime supports a subset. The unique tails must be clamped when emitting
+// to a runtime that does not support them:
+//   - 'max'     is Anthropic-only: Codex does not support it -> clamp to 'xhigh'
+//   - 'minimal' is Codex-only: Claude does not support it -> clamp to 'low'
+//
+// Rendering maps the universal effort string to the runtime's native parameter.
+
+const EFFORT_RENDERING = {
+  // Claude Code subagent effort: output_config.effort frontmatter key /
+  // CLAUDE_CODE_EFFORT_LEVEL env. Supports: low, medium, high, xhigh, max.
+  // Does NOT support 'minimal' (Codex-only) -> clamp to 'low'.
+  claude: {
+    param: 'output_config.effort',
+    channel: 'frontmatter',
+    supported: new Set(['low', 'medium', 'high', 'xhigh', 'max']),
+    clamp(level) {
+      if (level === 'minimal') return 'low';
+      return level;
+    },
+  },
+  // Codex Responses API reasoning.effort. Supports: minimal, low, medium, high, xhigh.
+  // Does NOT support 'max' (Anthropic-only) -> clamp to 'xhigh'.
+  codex: {
+    param: 'model_reasoning_effort',
+    channel: 'api',
+    supported: new Set(['minimal', 'low', 'medium', 'high', 'xhigh']),
+    clamp(level) {
+      if (level === 'max') return 'xhigh';
+      return level;
+    },
+  },
+};
+
+/**
+ * Render a universal effort string for a specific runtime.
+ *
+ * Returns { value (clamped), param, channel } where:
+ *   - value:   the clamped effort string safe to pass to the runtime
+ *   - param:   the native parameter name (e.g. 'output_config.effort')
+ *   - channel: how the value is propagated ('frontmatter', 'api', null)
+ *
+ * Unknown runtimes return { value: universalEffort, param: null, channel: null }
+ * so callers can always read .value safely.
+ */
+function renderEffortForRuntime(runtime, universalEffort) {
+  const spec = EFFORT_RENDERING[runtime];
+  if (!spec) {
+    return { value: universalEffort, param: null, channel: null };
+  }
+  return {
+    value: spec.clamp(universalEffort),
+    param: spec.param,
+    channel: spec.channel,
+  };
+}
+
+// ─── Fast mode propagation ───────────────────────────────────────────────────
+//
+// RUNTIMES_WITH_FAST_MODE is the set of runtimes where fast_mode=true can be
+// propagated to a SPAWNED SUBAGENT via a native mechanism.
+//
+// Claude Code has NO per-subagent fast-mode mechanism — /fast is a session-level
+// toggle only. Emitting a `fast_mode: true` frontmatter key on a Claude subagent
+// would be a SILENT NO-OP, which is why 'claude' is deliberately excluded here.
+//
+// Only API-direct runtimes ('api') accept a speed:"fast" field in the request.
+// Codex and other runtimes do not expose per-call fast_mode either.
+const RUNTIMES_WITH_FAST_MODE = new Set(['api']);
+
+module.exports = {
+  catalog,
+  MODEL_PROFILES,
+  VALID_PROFILES,
+  AGENT_TO_PHASE_TYPE,
+  VALID_PHASE_TYPES,
+  AGENT_DEFAULT_TIERS,
+  VALID_AGENT_TIERS,
+  MODEL_ALIAS_MAP,
+  RUNTIME_PROFILE_MAP,
+  KNOWN_RUNTIMES,
+  RUNTIMES_WITH_REASONING_EFFORT,
+  nextTier,
+  formatAgentToModelMapAsTable,
+  getAgentToModelMapForProfile,
+  EFFORT_RENDERING,
+  renderEffortForRuntime,
+  RUNTIMES_WITH_FAST_MODE,
+};

package/get-shit-done/bin/lib/model-profiles.cjs

@@ -0,0 +1,31 @@
+'use strict';
+
+const {
+  MODEL_PROFILES,
+  VALID_PROFILES,
+  AGENT_TO_PHASE_TYPE,
+  VALID_PHASE_TYPES,
+  AGENT_DEFAULT_TIERS,
+  VALID_AGENT_TIERS,
+  nextTier,
+  formatAgentToModelMapAsTable,
+  getAgentToModelMapForProfile,
+  EFFORT_RENDERING,
+  renderEffortForRuntime,
+  RUNTIMES_WITH_FAST_MODE,
+} = require('./model-catalog.cjs');
+
+module.exports = {
+  MODEL_PROFILES,
+  VALID_PROFILES,
+  AGENT_TO_PHASE_TYPE,
+  VALID_PHASE_TYPES,
+  AGENT_DEFAULT_TIERS,
+  VALID_AGENT_TIERS,
+  nextTier,
+  formatAgentToModelMapAsTable,
+  getAgentToModelMapForProfile,
+  EFFORT_RENDERING,
+  renderEffortForRuntime,
+  RUNTIMES_WITH_FAST_MODE,
+};

package/get-shit-done/bin/lib/observability/event.cjs

@@ -0,0 +1,82 @@
+'use strict';
+
+/**
+ * DispatchEvent shape factory — issue #177 (ADR-0174 P1.3), extended in #178 (P1.4).
+ *
+ * Creates a structured event record for every Hub dispatch, used by
+ * DispatchLogger to emit stderr errors and opt-in file audit trails.
+ *
+ * Shape:
+ *   traceId:       string           — UUID v4, generated per dispatch
+ *   parentTraceId: string|undefined — propagated from the caller when it is a canonical UUID v4
+ *                                     (RFC 4122); invalid values are silently coerced to undefined.
+ *                                     Enables a future init-composer (Phase 2) to correlate child
+ *                                     dispatches to their parent via the audit file.
+ *   command:       string  — the dispatched verb
+ *   args?:         unknown — only present when includeArgs === true
+ *   result:        { kind: 'ok' | 'UnknownCommand' | 'InvalidArgs' | 'HandlerRefusal' | 'HandlerFailure', ...payload }
+ *   timestamp:     string  — ISO 8601
+ */
+
+const { randomUUID } = require('crypto');
+
+/**
+ * Canonical UUID v4 regex (RFC 4122).
+ * - 36 characters total (32 hex + 4 hyphens)
+ * - Version nibble: 4
+ * - Variant bits: [89ab]
+ * - Case-insensitive: accepts both upper- and lowercase hex
+ *
+ * Used to validate parentTraceId before propagation. traceId is always
+ * generated internally by crypto.randomUUID() and is guaranteed valid.
+ */
+const UUID_V4_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+/**
+ * Returns true only when value is a canonical UUID v4 string.
+ * Any other value (non-string, wrong format, wrong version/variant) → false.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+function isValidParentTraceId(value) {
+  return typeof value === 'string' && UUID_V4_REGEX.test(value);
+}
+
+/**
+ * Create a DispatchEvent.
+ *
+ * @param {object} opts
+ * @param {string}   opts.command     - The dispatched command verb.
+ * @param {unknown}  [opts.args]      - Raw args passed to the hub.
+ * @param {object}   opts.result      - The HubResult returned by the hub.
+ * @param {boolean}  [opts.includeArgs=false] - When true, include args in the event.
+ * @param {string}   [opts.parentTraceId]     - Must be a canonical UUID v4 (RFC 4122).
+ *   Invalid values (non-string, wrong format, wrong version/variant) are silently coerced
+ *   to undefined — no stderr warn is emitted. This prevents correlation poisoning from
+ *   unvalidated caller input while keeping the factory pure and side-effect-free.
+ * @returns {object} Immutable DispatchEvent record.
+ */
+function makeDispatchEvent({ command, args, result, includeArgs = false, parentTraceId }) {
+  // Validate parentTraceId against UUID v4 format before propagation.
+  // Invalid inputs (empty string, non-UUID, UUID v1, oversized, etc.) are silently
+  // coerced to undefined. Silent coercion keeps the factory pure — no side effects,
+  // no log spam on bad input, consistent with how non-string values already collapse.
+  const resolvedParentTraceId = isValidParentTraceId(parentTraceId) ? parentTraceId : undefined;
+
+  const event = {
+    traceId: randomUUID(),
+    parentTraceId: resolvedParentTraceId,
+    command: String(command),
+    result,
+    timestamp: new Date().toISOString(),
+  };
+
+  if (includeArgs && args !== undefined) {
+    event.args = args;
+  }
+
+  return Object.freeze(event);
+}
+
+module.exports = { makeDispatchEvent };