@opengsd/gsd-core 1.2.0-rc.1

package/get-shit-done/bin/lib/check-command-router.cjs

@@ -0,0 +1,333 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+const { output, error, ERROR_REASON } = require('./core.cjs');
+const { parseDecisions } = require('./decisions.cjs');
+
+function normalizePhrase(text) {
+  return String(text || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9\s]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+const SOFT_PHRASE_MIN_WORDS = 6;
+
+function softPhrase(text) {
+  const words = normalizePhrase(text).split(' ').filter(Boolean);
+  if (words.length < SOFT_PHRASE_MIN_WORDS) return '';
+  return words.slice(0, SOFT_PHRASE_MIN_WORDS).join(' ');
+}
+
+function decisionMentioned(haystack, decision) {
+  if (!haystack) return false;
+  if (new RegExp(`\\b${decision.id}\\b`).test(haystack)) return true;
+  const phrase = softPhrase(decision.text);
+  return phrase ? normalizePhrase(haystack).includes(phrase) : false;
+}
+
+function readIfExists(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+function resolvePath(inputPath, projectDir) {
+  return path.isAbsolute(inputPath) ? inputPath : path.join(projectDir, inputPath);
+}
+
+function readWorkflowConfig(projectDir) {
+  const configPath = path.join(projectDir, '.planning', 'config.json');
+  try {
+    const parsed = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+    return {
+      ...(parsed.workflow || {}),
+      auto_advance: parsed.workflow?.auto_advance ?? parsed.auto_advance,
+      _auto_chain_active: parsed.workflow?._auto_chain_active ?? parsed._auto_chain_active,
+      context_coverage_gate: parsed.workflow?.context_coverage_gate ?? parsed.context_coverage_gate,
+    };
+  } catch {
+    return {};
+  }
+}
+
+function cmdAutoMode(projectDir, raw) {
+  const workflow = readWorkflowConfig(projectDir);
+  const autoAdvance = Boolean(workflow.auto_advance ?? false);
+  const autoChainActive = Boolean(workflow._auto_chain_active ?? false);
+  let source = 'none';
+  if (autoChainActive && autoAdvance) source = 'both';
+  else if (autoChainActive) source = 'auto_chain';
+  else if (autoAdvance) source = 'auto_advance';
+
+  output({
+    active: autoChainActive || autoAdvance,
+    source,
+    auto_chain_active: autoChainActive,
+    auto_advance: autoAdvance,
+  }, raw);
+}
+
+function gateEnabled(projectDir) {
+  const value = readWorkflowConfig(projectDir).context_coverage_gate;
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'string') {
+    const lower = value.toLowerCase();
+    if (lower === 'false' || lower === 'true') return lower !== 'false';
+  }
+  return true;
+}
+
+function loadPlanContents(phaseDir) {
+  if (!fs.existsSync(phaseDir)) return [];
+  try {
+    return fs.readdirSync(phaseDir)
+      .filter((entry) => /-PLAN\.md$/.test(entry))
+      .map((entry) => readIfExists(path.join(phaseDir, entry)));
+  } catch {
+    return [];
+  }
+}
+
+const DESIGNATED_HEADINGS_RE = /^#{1,6}\s+(?:must[_ ]haves?|truths?|tasks?|objective)\b/i;
+const XML_DECISION_TAGS_RE = /<(?:objective|tasks?|action)(?:\s[^>]*)?>([\s\S]*?)<\/(?:objective|tasks?|action)>/gi;
+
+function stripCommentsAndFences(text) {
+  return text
+    .replace(/<!--[\s\S]*?-->/g, ' ')
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/~~~[\s\S]*?~~~/g, ' ');
+}
+
+function extractYamlBlock(frontmatter, key) {
+  const match = frontmatter.match(new RegExp(`^${key}\\s*:(.*)$`, 'm'));
+  if (!match) return '';
+  const startIdx = (match.index || 0) + match[0].length;
+  const rest = frontmatter.slice(startIdx + 1).split(/\r?\n/);
+  const block = [match[1] || ''];
+  for (const line of rest) {
+    if (line === '' || /^\s/.test(line)) block.push(line);
+    else break;
+  }
+  return block.join('\n');
+}
+
+function extractXmlTagBodies(text) {
+  const parts = [];
+  for (const match of text.matchAll(XML_DECISION_TAGS_RE)) {
+    if (match[1]) parts.push(match[1]);
+  }
+  return parts.join('\n');
+}
+
+function extractPlanDesignatedSections(planContent) {
+  if (!planContent) return '';
+  const cleaned = stripCommentsAndFences(planContent);
+  const fmMatch = cleaned.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/);
+  const frontmatter = fmMatch ? fmMatch[1] : '';
+  const body = fmMatch ? fmMatch[2] : cleaned;
+
+  const parts = [];
+  for (const key of ['must_haves', 'truths', 'objective']) {
+    const block = extractYamlBlock(frontmatter, key);
+    if (block) parts.push(block);
+  }
+
+  const bodyParts = [];
+  let inDesignated = false;
+  for (const line of body.split(/\r?\n/)) {
+    const heading = /^#{1,6}\s+/.test(line);
+    if (heading) {
+      inDesignated = DESIGNATED_HEADINGS_RE.test(line);
+      if (inDesignated) bodyParts.push(line);
+      continue;
+    }
+    if (inDesignated) bodyParts.push(line);
+  }
+  parts.push(bodyParts.join('\n'));
+  parts.push(extractXmlTagBodies(cleaned));
+  return parts.join('\n\n');
+}
+
+function buildPlanMessage(uncovered) {
+  if (uncovered.length === 0) return 'All trackable CONTEXT.md decisions are covered by plans.';
+  return [
+    '## Decision Coverage Gap',
+    '',
+    `${uncovered.length} CONTEXT.md decision(s) are not covered by any plan:`,
+    '',
+    ...uncovered.map((item) => `- **${item.id}** (${item.category || 'uncategorized'}): ${item.text}`),
+    '',
+    'Resolve by citing `D-NN:` in a relevant plan\'s `must_haves`/`truths` (or body),',
+    'OR move the decision to `### Claude\'s Discretion` / tag it `[informational]` if it should not be tracked.',
+  ].join('\n');
+}
+
+function buildVerifyMessage(notHonored) {
+  if (notHonored.length === 0) return 'All trackable CONTEXT.md decisions are honored by shipped artifacts.';
+  return [
+    '### Decision Coverage (warning)',
+    '',
+    `${notHonored.length} decision(s) not found in shipped artifacts:`,
+    '',
+    ...notHonored.map((item) => `- **${item.id}** (${item.category || 'uncategorized'}): ${item.text}`),
+    '',
+    'This is a soft warning - verification status is unchanged.',
+  ].join('\n');
+}
+
+function loadTrackableDecisions(contextPath) {
+  return parseDecisions(readIfExists(contextPath)).filter((decision) => decision.trackable);
+}
+
+function cmdDecisionCoveragePlan(projectDir, args, raw) {
+  const phaseDir = args[2] ? resolvePath(args[2], projectDir) : '';
+  const contextPath = args[3] ? resolvePath(args[3], projectDir) : '';
+
+  if (!gateEnabled(projectDir)) {
+    output({ passed: true, skipped: true, reason: 'workflow.context_coverage_gate is false', total: 0, covered: 0, uncovered: [], message: 'Decision coverage gate disabled by config.' }, raw);
+    return;
+  }
+  if (!contextPath || !fs.existsSync(contextPath)) {
+    output({ passed: true, skipped: true, reason: 'CONTEXT.md missing', total: 0, covered: 0, uncovered: [], message: 'No CONTEXT.md - nothing to check.' }, raw);
+    return;
+  }
+
+  const decisions = loadTrackableDecisions(contextPath);
+  if (decisions.length === 0) {
+    output({ passed: true, skipped: true, reason: 'no trackable decisions', total: 0, covered: 0, uncovered: [], message: 'No trackable decisions in CONTEXT.md.' }, raw);
+    return;
+  }
+
+  const sections = loadPlanContents(phaseDir).map(extractPlanDesignatedSections);
+  const uncovered = [];
+  let covered = 0;
+  for (const decision of decisions) {
+    if (sections.some((section) => decisionMentioned(section, decision))) covered++;
+    else uncovered.push({ id: decision.id, text: decision.text, category: decision.category });
+  }
+
+  output({
+    passed: uncovered.length === 0,
+    skipped: false,
+    total: decisions.length,
+    covered,
+    uncovered,
+    message: buildPlanMessage(uncovered),
+  }, raw);
+}
+
+function recentCommitMessages(projectDir) {
+  try {
+    return execFileSync('git', ['log', '-n', '200', '--pretty=%s%n%b'], {
+      cwd: projectDir,
+      encoding: 'utf-8',
+      maxBuffer: 4 * 1024 * 1024,
+    });
+  } catch {
+    return '';
+  }
+}
+
+function isInsideRoot(candidatePath, rootDir) {
+  const root = path.resolve(rootDir);
+  const target = path.resolve(root, candidatePath);
+  return target === root || target.startsWith(`${root}${path.sep}`);
+}
+
+function readModifiedFilesContent(projectDir, summaries) {
+  const out = [];
+  let total = 0;
+  for (const summary of summaries) {
+    if (!summary) continue;
+    for (const blockMatch of summary.matchAll(/files_modified:\s*\n((?:[ \t]*-\s+.+\n?)+)/g)) {
+      const files = [...(blockMatch[1] || '').matchAll(/-\s+(.+)/g)]
+        .map((match) => match[1].trim().replace(/^["']|["']$/g, ''));
+      for (const file of files) {
+        if (total >= 50) break;
+        if (!file || !isInsideRoot(file, projectDir)) continue;
+        const raw = readIfExists(resolvePath(file, projectDir));
+        out.push(raw.length > 256 * 1024 ? raw.slice(0, 256 * 1024) : raw);
+        total++;
+      }
+      if (total >= 50) break;
+    }
+    if (total >= 50) break;
+  }
+  return out.join('\n\n');
+}
+
+function cmdDecisionCoverageVerify(projectDir, args, raw) {
+  const phaseDir = args[2] ? resolvePath(args[2], projectDir) : '';
+  const contextPath = args[3] ? resolvePath(args[3], projectDir) : '';
+
+  if (!gateEnabled(projectDir)) {
+    output({ skipped: true, blocking: false, reason: 'workflow.context_coverage_gate is false', total: 0, honored: 0, not_honored: [], message: 'Decision coverage gate disabled by config.' }, raw);
+    return;
+  }
+  if (!contextPath || !fs.existsSync(contextPath)) {
+    output({ skipped: true, blocking: false, reason: 'CONTEXT.md missing', total: 0, honored: 0, not_honored: [], message: 'No CONTEXT.md - nothing to check.' }, raw);
+    return;
+  }
+
+  const decisions = loadTrackableDecisions(contextPath);
+  if (decisions.length === 0) {
+    output({ skipped: true, blocking: false, reason: 'no trackable decisions', total: 0, honored: 0, not_honored: [], message: 'No trackable decisions in CONTEXT.md.' }, raw);
+    return;
+  }
+
+  const planContents = loadPlanContents(phaseDir);
+  const summaryParts = fs.existsSync(phaseDir)
+    ? fs.readdirSync(phaseDir).filter((entry) => /-SUMMARY\.md$/.test(entry)).map((entry) => readIfExists(path.join(phaseDir, entry)))
+    : [];
+  const haystack = [
+    planContents.join('\n\n'),
+    summaryParts.join('\n\n'),
+    readModifiedFilesContent(projectDir, summaryParts),
+    recentCommitMessages(projectDir),
+  ].join('\n\n');
+
+  const notHonored = [];
+  let honored = 0;
+  for (const decision of decisions) {
+    if (decisionMentioned(haystack, decision)) honored++;
+    else notHonored.push({ id: decision.id, text: decision.text, category: decision.category });
+  }
+
+  output({
+    skipped: false,
+    blocking: false,
+    total: decisions.length,
+    honored,
+    not_honored: notHonored,
+    message: buildVerifyMessage(notHonored),
+  }, raw);
+}
+
+function routeCheckCommand({ args, cwd, raw }) {
+  const subcommand = args[1];
+  if (subcommand === 'auto-mode') {
+    cmdAutoMode(cwd, raw);
+    return;
+  }
+  if (subcommand === 'decision-coverage-plan') {
+    cmdDecisionCoveragePlan(cwd, args, raw);
+    return;
+  }
+  if (subcommand === 'decision-coverage-verify') {
+    cmdDecisionCoverageVerify(cwd, args, raw);
+    return;
+  }
+  error('Unknown check subcommand. Available: auto-mode, decision-coverage-plan, decision-coverage-verify', ERROR_REASON.SDK_UNKNOWN_COMMAND);
+}
+
+module.exports = {
+  routeCheckCommand,
+  decisionMentioned,
+  extractPlanDesignatedSections,
+};

package/get-shit-done/bin/lib/cjs-command-router-adapter.cjs

@@ -0,0 +1,118 @@
+'use strict';
+
+const { createHub, ERROR_KINDS } = require('./command-routing-hub.cjs');
+
+/**
+ * CJS Command Router Adapter Module
+ *
+ * Compatibility routing for gsd-tools.cjs command families. Uses generated
+ * command metadata for availability and small family-local argument shapers for
+ * CJS handler calls.
+ */
+
+function routeCjsCommandFamily({
+  args,
+  subcommands,
+  handlers,
+  defaultSubcommand,
+  unsupported = {},
+  unknownMessage,
+  error,
+  cwd,
+  raw,
+}) {
+  routeHubCommandFamily({
+    family: '__legacy_cjs_family__',
+    args,
+    subcommands,
+    handlers,
+    defaultSubcommand,
+    unsupported,
+    unknownMessage,
+    error,
+    cwd,
+    raw,
+  });
+}
+
+/**
+ * Hub-backed family router adapter.
+ *
+ * Deepens the command-topology seam by routing family handlers through
+ * CommandRoutingHub's typed Result contract instead of ad-hoc per-router
+ * lookup + error handling branches.
+ */
+function routeHubCommandFamily({
+  family,
+  args,
+  subcommands,
+  handlers,
+  defaultSubcommand,
+  unsupported = {},
+  unknownMessage,
+  error,
+  cwd,
+  raw,
+}) {
+  const subcommand = args[1] || defaultSubcommand;
+
+  if (subcommand && unsupported[subcommand]) {
+    error(unsupported[subcommand]);
+    return;
+  }
+
+  const available = subcommands.filter((s) => !unsupported[s]);
+  const registryHandlers = Object.fromEntries(
+    Object.entries(handlers).map(([name, handler]) => [
+      name,
+      () => {
+        const result = handler();
+        if (result && typeof result === 'object' && Object.prototype.hasOwnProperty.call(result, 'ok')) {
+          return result;
+        }
+        return { ok: true, data: null };
+      },
+    ]),
+  );
+
+  const hub = createHub({
+    cjsRegistry: { [family]: registryHandlers },
+    manifest: { [family]: available },
+  });
+
+  const result = hub.dispatch({
+    family,
+    subcommand,
+    args: args.slice(2),
+    cwd,
+    raw,
+  });
+
+  if (result.ok) return;
+  if (result.kind === ERROR_KINDS.UnknownCommand) {
+    error(unknownMessage(subcommand, available));
+    return;
+  }
+  if (result.kind === ERROR_KINDS.InvalidArgs || result.kind === ERROR_KINDS.HandlerRefusal) {
+    error(result.reason);
+    return;
+  }
+  error(result.message);
+}
+
+/**
+ * Projection helper for family routers that still declare SDK registry metadata
+ * but execute the CJS fallback path at this seam.
+ *
+ * Accepts variable argument shapes so routers can pass legacy projection tuples
+ * (`registryCommand`, `registryArgs`, `legacyArgs`, optional `rawFormatter`, `cjsFallback`).
+ */
+function cjsFallbackHandler(...projectionArgs) {
+  return projectionArgs[projectionArgs.length - 1];
+}
+
+module.exports = {
+  routeCjsCommandFamily,
+  routeHubCommandFamily,
+  cjsFallbackHandler,
+};

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

@@ -0,0 +1,96 @@
+'use strict';
+
+/**
+ * Deterministic clock seam for lock modules (issue #453).
+ *
+ * Production code uses `realClock` (the default). Test code passes in a
+ * `makeFakeClock()` instance to drive lock timing without real wall-clock
+ * waits or Atomics.wait calls.
+ *
+ * Both methods in realClock use exactly the same system primitives that
+ * acquireStateLock and withPlanningLock used inline before the seam was
+ * introduced:
+ *   - now()   → Date.now()
+ *   - sleep() → Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms)
+ */
+
+// Module-level Atomics.wait buffer reused across every realClock.sleep() call.
+// The buffer value is always 0 (never written), so reuse is semantically
+// identical to allocating a fresh buffer each time.
+const _realSleepBuf = new Int32Array(new SharedArrayBuffer(4));
+
+/**
+ * Parse GSD_NOW_MS to a valid pinned epoch millisecond value, or return null.
+ *
+ * Accepts ONLY strict decimal integer strings within JS Date bounds
+ * (abs(ms) <= 8.64e15).  Rejects empty strings, whitespace-only, floats
+ * ('12.5'), scientific notation ('1e30'), and out-of-range values.
+ *
+ * Returns null (fall back to Date.now()) for any invalid or absent input.
+ * Returns null when GSD_TEST_MODE is not set.
+ *
+ * @returns {number|null}
+ */
+function _pinnedNowMs() {
+  if (!process.env.GSD_TEST_MODE) return null;
+  const raw = process.env.GSD_NOW_MS;
+  if (typeof raw !== 'string') return null;
+  const t = raw.trim();
+  if (!/^-?\d+$/.test(t)) return null;          // reject '', 'abc', '1e30', '12.5'
+  const ms = Number(t);
+  if (!Number.isFinite(ms) || Math.abs(ms) > 8.64e15) return null;  // Date-valid bounds
+  return ms;
+}
+
+const realClock = {
+  /**
+   * Return current epoch milliseconds.
+   *
+   * When both GSD_TEST_MODE and GSD_NOW_MS are set (subprocess time-pin adapter,
+   * issue #474), returns the pinned millisecond value so all date-stamping in the
+   * subprocess SUT is deterministic.  In production, falls back to Date.now().
+   *
+   * Only strict decimal integer strings within JS Date bounds are accepted as pins.
+   * Any other value (empty string, float, scientific notation, out-of-range) falls
+   * back to Date.now() to prevent RangeError from new Date(ms).toISOString().
+   */
+  now() {
+    const pinned = _pinnedNowMs();
+    if (pinned !== null) return pinned;
+    return Date.now();
+  },
+
+  /**
+   * Return the current instant as an ISO 8601 string (UTC).
+   * Uses this.now() so the subprocess time-pin adapter is honoured.
+   *
+   * @returns {string} e.g. "2020-06-15T12:00:00.000Z"
+   */
+  nowIso() {
+    return new Date(this.now()).toISOString();
+  },
+
+  /**
+   * Return today's date as a YYYY-MM-DD string (UTC calendar day).
+   * Uses this.now() so the subprocess time-pin adapter is honoured.
+   *
+   * @returns {string} e.g. "2020-06-15"
+   */
+  today() {
+    return this.nowIso().split('T')[0];
+  },
+
+  /**
+   * Synchronous sleep via Atomics.wait.
+   * This is the identical primitive acquireStateLock and withPlanningLock used
+   * inline before the seam.  Atomics.wait on a shared buffer that is never
+   * notified times out after exactly `ms` milliseconds without spinning the CPU.
+   *
+   * @param {number} ms - milliseconds to sleep
+   */
+  sleep(ms) {
+    Atomics.wait(_realSleepBuf, 0, 0, ms);
+  },
+};
+
+module.exports = { realClock };

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

@@ -0,0 +1,135 @@
+'use strict';
+/**
+ * Skill cluster definitions for the runtime surface module (ADR-0011 Phase 2).
+ *
+ * Each cluster is a named group of skill stems. Clusters are used by /gsd:surface
+ * to enable/disable a cohesive group of skills without reinstall.
+ *
+ * Cluster membership may overlap (a skill can live in two clusters). The union
+ * of all clusters should cover every installed skill stem; uncategorized stems
+ * are flagged by surface-clusters.test.cjs.
+ *
+ * Source: docs/research/2026-05-12-skill-surface-budget.md §3.2 (verified
+ * against commands/gsd/ listing in surface-clusters.test.cjs).
+ */
+
+const CLUSTERS = Object.freeze({
+  core_loop: Object.freeze([
+    'new-project',
+    'discuss-phase',
+    'plan-phase',
+    'execute-phase',
+    'help',
+    'update',
+  ]),
+
+  audit_review: Object.freeze([
+    'code-review',
+    'review',
+    'audit-fix',
+    'audit-milestone',
+    'audit-uat',
+    'verify-work',
+    'validate-phase',
+    'plan-review-convergence',
+    'eval-review',
+    'add-tests',
+    'secure-phase',
+  ]),
+
+  milestone: Object.freeze([
+    'new-milestone',
+    'complete-milestone',
+    'milestone-summary',
+    'health',
+  ]),
+
+  research_ideate: Object.freeze([
+    'sketch',
+    'spike',
+    'forensics',
+    'explore',
+    'graphify',
+    'ns-ideate',
+  ]),
+
+  workspace_state: Object.freeze([
+    'pause-work',
+    'resume-work',
+    'workspace',
+    'workstreams',
+    'thread',
+    'capture',
+    'inbox',
+  ]),
+
+  docs: Object.freeze([
+    'docs-update',
+    'ingest-docs',
+  ]),
+
+  ui: Object.freeze([
+    'ui-phase',
+    'ui-review',
+  ]),
+
+  ai_eval: Object.freeze([
+    'ai-integration-phase',
+    'eval-review',
+  ]),
+
+  ns_meta: Object.freeze([
+    'ns-context',
+    'ns-ideate',
+    'ns-manage',
+    'ns-project',
+    'ns-review',
+    'ns-workflow',
+  ]),
+
+  utility: Object.freeze([
+    'health',
+    'stats',
+    'settings',
+    'cleanup',
+    'pr-branch',
+    'ship',
+    'undo',
+    'fast',
+    'quick',
+    'autonomous',
+    'config',
+    'progress',
+    'phase',
+    'review',
+    'update',
+    'help',
+    'code-review',
+    'import',
+    'manager',
+    'map-codebase',
+    'profile-user',
+    'spec-phase',
+    'ultraplan-phase',
+    'mvp-phase',
+    'execute-phase',
+    'review-backlog',
+    'debug',
+    'extract-learnings',
+    'surface',
+  ]),
+});
+
+/**
+ * Build a Set of all skill stems covered by at least one cluster.
+ * @returns {Set<string>}
+ */
+function allClusteredSkills() {
+  const result = new Set();
+  for (const skills of Object.values(CLUSTERS)) {
+    for (const s of skills) result.add(s);
+  }
+  return result;
+}
+
+module.exports = { CLUSTERS, allClusteredSkills };