@entelligentsia/forgecli 0.7.9 → 0.8.4

package/dist/forge-payload/tools/lib/suggest.cjs

@@ -0,0 +1,211 @@
+'use strict';
+
+// Vocab-drift detector + "Did you mean?" suggestion engine (FORGE-S22-T03)
+//
+// Provides Levenshtein-based fuzzy matching with a curated DRIFT_MAP for
+// high-frequency agent misconception patterns that pure distance alone cannot
+// resolve (e.g., "task" → "taskId", "completed" → "committed").
+//
+// Suggestion pipeline (apply in order):
+//   1. Store original input
+//   2. Normalize (underscores → hyphens)
+//   3. Suppress if original exactly matches a valid candidate (true noise)
+//   4. Normalization-hint: if normalized matches a candidate but original doesn't,
+//      suggest the normalized form (underscore→hyphen hint)
+//   5. DRIFT_MAP exact match (after normalization), intersected with candidate pool
+//   6. Levenshtein fallback (distance ≤ 2, max 3 suggestions)
+//   7. Format as "(Did you mean ...?)" string
+
+const MAX_CANDIDATES = 200;
+const DEFAULT_MAX_DIST = 2;
+const MAX_SUGGESTIONS = 3;
+
+// ---------------------------------------------------------------------------
+// Levenshtein distance
+// ---------------------------------------------------------------------------
+
+/**
+ * Compute the Levenshtein distance between two strings.
+ * @param {string} a
+ * @param {string} b
+ * @returns {number}
+ */
+function levenshtein(a, b) {
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+
+  // Swap so that the shorter string is b (reduces memory)
+  if (a.length < b.length) {
+    const tmp = a; a = b; b = tmp;
+  }
+
+  const prevRow = new Array(b.length + 1);
+  for (let j = 0; j <= b.length; j++) prevRow[j] = j;
+
+  for (let i = 1; i <= a.length; i++) {
+    const curRow = new Array(b.length + 1);
+    curRow[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curRow[j] = Math.min(
+        curRow[j - 1] + 1,       // insertion
+        prevRow[j] + 1,           // deletion
+        prevRow[j - 1] + cost    // substitution
+      );
+    }
+    // Copy curRow into prevRow for next iteration
+    for (let j = 0; j <= b.length; j++) prevRow[j] = curRow[j];
+  }
+
+  return prevRow[b.length];
+}
+
+// ---------------------------------------------------------------------------
+// Normalization
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalize a string for matching: replace underscores with hyphens.
+ * @param {string} s
+ * @returns {string}
+ */
+function normalizeForMatch(s) {
+  return s.replace(/_/g, '-');
+}
+
+// ---------------------------------------------------------------------------
+// DRIFT_MAP
+// ---------------------------------------------------------------------------
+
+/**
+ * Curated drift map for high-frequency agent misconceptions.
+ * Keys are *normalized* input strings; values are arrays of suggested targets.
+ * Targets are intersected against the candidate pool at suggest-time.
+ */
+const DRIFT_MAP = {
+  'task':           ['taskId'],
+  'completed':      ['committed'],
+  'in-progress':    ['implementing'],
+  'timestamp':      ['startTimestamp', 'endTimestamp'],
+  'task-completed': ['task-committed'],
+  'implemented':    ['implementing'],
+  'set':            ['set-summary'],
+  'start':          ['startTimestamp']
+};
+
+// ---------------------------------------------------------------------------
+// suggest() — main suggestion pipeline
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate "Did you mean?" suggestions for an input string.
+ *
+ * @param {string} input        The misspelled/invalid input string
+ * @param {string[]} candidates Valid candidate strings
+ * @param {object} [opts]       Options
+ * @param {number} [opts.maxDist=2]        Maximum Levenshtein distance
+ * @param {number} [opts.maxCandidates=200] Safety guard — return [] if pool exceeds this
+ * @returns {string[]} Array of suggested corrections (0–3 items)
+ */
+function suggest(input, candidates, opts) {
+  if (!input || !Array.isArray(candidates) || candidates.length === 0) return [];
+
+  const maxDist = (opts && opts.maxDist !== undefined) ? opts.maxDist : DEFAULT_MAX_DIST;
+  const maxCandidates = (opts && opts.maxCandidates !== undefined) ? opts.maxCandidates : MAX_CANDIDATES;
+
+  // Safety guard: don't process enormous candidate pools
+  if (candidates.length > maxCandidates) return [];
+
+  const original = String(input);
+  const normalized = normalizeForMatch(original);
+
+  // Step 3: Suppress if original exactly matches a valid candidate (true noise)
+  if (candidates.includes(original)) return [];
+
+  // Step 4: Normalization-hint — if normalized matches a candidate but original doesn't
+  if (normalized !== original && candidates.includes(normalized)) {
+    return [normalized];
+  }
+
+  // Step 5: DRIFT_MAP exact match (after normalization), intersected with candidate pool
+  if (DRIFT_MAP[normalized]) {
+    const filtered = DRIFT_MAP[normalized].filter(function(t) {
+      return candidates.includes(t);
+    });
+    if (filtered.length > 0) return filtered.slice(0, MAX_SUGGESTIONS);
+    // If no DRIFT_MAP targets are in the pool, fall through to Levenshtein
+  }
+
+  // Step 6: Levenshtein fallback
+  const scored = [];
+  for (let i = 0; i < candidates.length; i++) {
+    const candidate = candidates[i];
+    const d = levenshtein(normalized, candidate);
+    if (d <= maxDist && d > 0) {
+      scored.push({ candidate: candidate, distance: d });
+    }
+  }
+
+  // Sort by distance ascending, then alphabetically
+  scored.sort(function(a, b) {
+    if (a.distance !== b.distance) return a.distance - b.distance;
+    return a.candidate < b.candidate ? -1 : a.candidate > b.candidate ? 1 : 0;
+  });
+
+  const results = [];
+  for (let i = 0; i < Math.min(MAX_SUGGESTIONS, scored.length); i++) {
+    results.push(scored[i].candidate);
+  }
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// suggestEntityType() — shared helper for entity-type error sites
+// ---------------------------------------------------------------------------
+
+/**
+ * Suggest entity types for an invalid input. Uses a narrower default pool
+ * that excludes 'event' for commands that don't handle events.
+ *
+ * @param {string} input           The invalid entity type string
+ * @param {string[]} [candidates] Valid entity types (defaults to all 5)
+ * @returns {string[]} Array of suggested entity types
+ */
+function suggestEntityType(input, candidates) {
+  const pool = candidates || ['sprint', 'task', 'bug', 'event', 'feature'];
+  return suggest(input, pool);
+}
+
+// ---------------------------------------------------------------------------
+// formatSuggestion() — render suggestions as "(Did you mean ...?)" string
+// ---------------------------------------------------------------------------
+
+/**
+ * Format an array of suggestions into a human-readable "(Did you mean ...?)" string.
+ *
+ * @param {string[]} suggestions Array of 1–3 suggestion strings
+ * @returns {string} Formatted string, e.g. '(Did you mean "X"?)' or empty string
+ */
+function formatSuggestion(suggestions) {
+  if (!Array.isArray(suggestions) || suggestions.length === 0) return '';
+
+  const quoted = suggestions.map(function(s) { return '"' + s + '"'; });
+
+  if (quoted.length === 1) {
+    return '(Did you mean ' + quoted[0] + '?)';
+  }
+  if (quoted.length === 2) {
+    return '(Did you mean ' + quoted[0] + ' or ' + quoted[1] + '?)';
+  }
+  // 3 items: Oxford comma
+  return '(Did you mean ' + quoted[0] + ', ' + quoted[1] + ', or ' + quoted[2] + '?)';
+}
+
+module.exports = {
+  levenshtein,
+  normalizeForMatch,
+  suggest,
+  suggestEntityType,
+  formatSuggestion,
+  DRIFT_MAP
+};

package/dist/forge-payload/tools/lib/validate.js

@@ -15,6 +15,9 @@
 // Not supported (by design): $ref, allOf/anyOf/oneOf, propertyNames,
 // dependencies, const. Schemas can express what Forge needs without them.
 
+// FORGE-S22-T03: import suggestion engine for "Did you mean?" on enum/field errors
+const { suggest, formatSuggestion } = require('./suggest.cjs');
+
 // Fields that may legitimately be null (nullable FKs / optional timing).
 // Mirrors store-cli.cjs — keep in sync.
 const NULLABLE_FIELDS = new Set([
@@ -74,7 +77,9 @@ function validateRecord(record, schema, opts) {
     }
 
     if (def.enum && !def.enum.includes(val)) {
-      errors.push(`${field}: value "${val}" not in [${def.enum.join(', ')}]`);
+      const enumSuggestions = suggest(String(val), def.enum);
+      const suggestionStr = formatSuggestion(enumSuggestions);
+      errors.push(`${field}: value "${val}" not in [${def.enum.join(', ')}]${suggestionStr ? ' ' + suggestionStr : ''}`);
     }
 
     if (def.minimum !== undefined && typeof val === 'number' && val < def.minimum) {
@@ -120,8 +125,13 @@ function validateRecord(record, schema, opts) {
 
   if (schema.additionalProperties === false) {
     const allowed = new Set(Object.keys(properties));
+    const fieldNames = Object.keys(properties);
     for (const key of Object.keys(record)) {
-      if (!allowed.has(key)) errors.push(`${key}: undeclared field`);
+      if (!allowed.has(key)) {
+        const fieldSuggestions = suggest(key, fieldNames);
+        const suggestionStr = formatSuggestion(fieldSuggestions);
+        errors.push(`${key}: undeclared field${suggestionStr ? ' ' + suggestionStr : ''}`);
+      }
     }
   }
 

package/dist/forge-payload/tools/store-cli.cjs

@@ -133,6 +133,9 @@ const MINIMAL_REQUIRED = {
 // write-boundary hook can reuse the exact same validation logic as tool writes.
 const { validateRecord, NULLABLE_FIELDS } = require('./lib/validate.js');
 
+// FORGE-S22-T03: suggestion engine for "Did you mean?" on validation/transition errors
+const { suggest, suggestEntityType, formatSuggestion } = require('./lib/suggest.cjs');
+
 // Valid phase keys for summaries (dot-delimited → underscore in JSON key)
 const VALID_SUMMARY_PHASES = new Set(['plan', 'review_plan', 'implementation', 'code_review', 'validation', 'triage', 'approve']);
 
@@ -359,7 +362,7 @@ function deleteEntity(entity, id) {
     case 'bug':     return store.deleteBug(id);
     case 'feature': return store.deleteFeature(id);
     default:
-      console.error(`Unknown entity type: ${entity}`);
+      console.error(`Unknown entity type: ${entity}${formatSuggestion(suggestEntityType(entity, ['sprint', 'task', 'bug', 'feature']))}`);
       process.exit(1);
   }
 }
@@ -371,7 +374,7 @@ function listEntities(entity, filter) {
     case 'bug':     return store.listBugs(filter);
     case 'feature': return store.listFeatures(filter);
     default:
-      console.error(`Unknown entity type: ${entity}`);
+      console.error(`Unknown entity type: ${entity}${formatSuggestion(suggestEntityType(entity, ['sprint', 'task', 'bug', 'feature']))}`);
       process.exit(1);
   }
 }
@@ -431,7 +434,7 @@ Commands:
   delete <entity> <id>                        Delete an entity record
   update-status <entity> <id> <field> <value> [--force]
                                               Update status/enum field with transition check
-  emit <sprintId> '<json>' [--sidecar]        Write an event (or sidecar)
+  emit <sprintId> '<json>' [--sidecar] [--allow-synthetic]  Write an event (or sidecar)
   merge-sidecar <sprintId> <eventId>          Merge sidecar into canonical event
   record-usage <sprintId> <eventId> [flags]  Write a token-usage sidecar
   purge-events <sprintId>                     Delete all events for a sprint
@@ -447,6 +450,14 @@ Commands:
   describe <entity>                           Print the JSON Schema for an entity
   template <entity>                           Print a canonical sample record (required fields populated)
 
+Alias commands:
+  get <entity> <id> [--json]                  Alias for: read <entity> <id> [--json]
+  get-task <id> [--json]                      Alias for: read task <id> [--json]
+  get-bug <id> [--json]                       Alias for: read bug <id> [--json]
+  get-sprint <id> [--json]                    Alias for: read sprint <id> [--json]
+  get-summary <taskId> <phase> [--json]       Read summaries[phase] from a task record
+  get-bug-summary <bugId> <phase> [--json]    Read summaries[phase] from a bug record
+
 Entities: sprint, task, bug, event, feature
 Phases (summaries): plan, review_plan, implementation, code_review, validation
 
@@ -456,13 +467,59 @@ Flags:
                FORGE_ALLOW_FORCE=1 in the environment. Subagents MUST NOT use this;
                surface the illegal transition to the orchestrator instead.
   --json       Output raw JSON on read (no pretty-print)
-  --sidecar    Write as sidecar file on emit (ephemeral _-prefixed)
+  --sidecar          Write as sidecar file on emit (ephemeral _-prefixed)
+  --allow-synthetic  Bypass sprintId FK check on emit (for synthetic/test events)
 
 Exit codes: 0 on success, 1 on failure`);
   process.exit(0);
 }
 
-const command = args[0];
+// ---------------------------------------------------------------------------
+// Alias dispatch table (FORGE-S22-T02)
+//
+// Read-aliases delegate to `cmdRead` by rewriting argv before the main switch.
+// Summary read-throughs (`get-summary`, `get-bug-summary`) are NOT in this
+// map — they are registered as direct cases in the switch below to avoid
+// any chance of routing through a write verb.
+//
+// Entries:
+//   target          — canonical command this alias rewrites to
+//   entity          — if set, inserted as the first positional arg (so
+//                     `get-task <id>` becomes `read task <id>`)
+//   injectEntity:false — bare `get`; requires the caller to supply the
+//                     entity as args[1]. Validated below.
+// ---------------------------------------------------------------------------
+const ALIAS_MAP = {
+  'get':        { target: 'read', injectEntity: false },
+  'get-task':   { target: 'read', entity: 'task'   },
+  'get-bug':    { target: 'read', entity: 'bug'    },
+  'get-sprint': { target: 'read', entity: 'sprint' },
+};
+
+let command = args[0];
+
+if (Object.prototype.hasOwnProperty.call(ALIAS_MAP, command)) {
+  const entry = ALIAS_MAP[command];
+  // Drop the alias verb from args; the remainder are positionals + flags.
+  args.splice(0, 1);
+  if (entry.entity) {
+    // `get-task <id>` → args becomes [<id>, ...flags]; prepend entity so the
+    // downstream cmdRead sees [entity, id, ...flags].
+    args.unshift(entry.entity);
+  } else if (entry.injectEntity === false) {
+    // Bare `get`: caller must have supplied `<entity> <id>`. Split flags from
+    // positionals so we validate the first positional, not a flag.
+    const positionals = args.filter((a) => !a.startsWith('--'));
+    if (positionals.length < 2 || !ENTITY_TYPES.includes(positionals[0])) {
+      console.error("error: 'get' requires an entity type — usage: get <task|bug|sprint> <id>");
+      process.exit(1);
+    }
+  }
+  command = entry.target;
+  // Reconstruct argv so cmdRead, which reads args[1]/args[2], sees the
+  // rewritten shape `[command, entity, id, ...flags]`.
+  args.unshift(command);
+}
 
 // ---------------------------------------------------------------------------
 // Command implementations
@@ -478,7 +535,7 @@ function cmdWrite() {
   }
 
   if (!ENTITY_TYPES.includes(entity)) {
-    console.error(`Unknown entity type: ${entity}`);
+    console.error(`Unknown entity type: ${entity}${formatSuggestion(suggestEntityType(entity))}`);
     process.exit(1);
   }
 
@@ -522,7 +579,7 @@ function cmdRead() {
   }
 
   if (!ENTITY_TYPES.includes(entity)) {
-    console.error(`Unknown entity type: ${entity}`);
+    console.error(`Unknown entity type: ${entity}${formatSuggestion(suggestEntityType(entity))}`);
     process.exit(1);
   }
 
@@ -562,7 +619,7 @@ function cmdList() {
   }
 
   if (!ENTITY_TYPES.includes(entity)) {
-    console.error(`Unknown entity type: ${entity}`);
+    console.error(`Unknown entity type: ${entity}${formatSuggestion(suggestEntityType(entity, ['sprint', 'task', 'bug', 'feature']))}`);
     process.exit(1);
   }
 
@@ -593,7 +650,7 @@ function cmdDelete() {
   }
 
   if (!ENTITY_TYPES.includes(entity)) {
-    console.error(`Unknown entity type: ${entity}`);
+    console.error(`Unknown entity type: ${entity}${formatSuggestion(suggestEntityType(entity, ['sprint', 'task', 'bug', 'feature']))}`);
     process.exit(1);
   }
 
@@ -614,7 +671,13 @@ function cmdUpdateStatus() {
   }
 
   if (!TRANSITION_MAP[entity]) {
-    console.error(`No transition rules for entity type: ${entity}`);
+    const transitionTypes = Object.keys(TRANSITION_MAP);
+    const sug = suggestEntityType(entity, transitionTypes);
+    if (sug.length > 0) {
+      console.error(`No transition rules for entity type: ${entity} ${formatSuggestion(sug)}`);
+    } else {
+      console.error(`No transition rules for entity type: ${entity}. Valid types: ${transitionTypes.join(', ')}`);
+    }
     process.exit(1);
   }
 
@@ -641,7 +704,11 @@ function cmdUpdateStatus() {
 
   // Check transition legality
   if (!force && !isLegalTransition(entity, field, currentValue, value)) {
-    console.error(`Illegal transition: ${entity} ${id} ${field}: ${currentValue} → ${value}`);
+    const legalTargets = TRANSITION_MAP[entity] && TRANSITION_MAP[entity][currentValue]
+      ? TRANSITION_MAP[entity][currentValue]
+      : [];
+    const transitionSuggestions = suggest(value, legalTargets);
+    console.error(`Illegal transition: ${entity} ${id} ${field}: ${currentValue} → ${value}` + (formatSuggestion(transitionSuggestions) ? ' ' + formatSuggestion(transitionSuggestions) : ''));
     process.exit(1);
   }
 
@@ -689,16 +756,59 @@ function _normalizeEventTimestamps(data) {
   return data;
 }
 
+// resolveValidSprintIds() — reads .forge/store/sprints/ and returns an array
+// of sprintId strings (filenames without .json extension). Returns [] on ENOENT
+// so fresh installs without a sprints dir don't crash.
+// Not exported — CLI-only concern.
+function resolveValidSprintIds() {
+  try {
+    const storeRoot = store.storeRoot || '.forge/store';
+    const sprintsDir = path.join(storeRoot, 'sprints');
+    return fs.readdirSync(sprintsDir)
+      .filter(f => f.endsWith('.json'))
+      .map(f => f.slice(0, -5));
+  } catch (e) {
+    if (e.code === 'ENOENT') return [];
+    throw e;
+  }
+}
+
 function cmdEmit() {
   const sprintId = args[1];
   const jsonStr = args[2];
   const isSidecar = args.includes('--sidecar');
+  const allowSynthetic = args.includes('--allow-synthetic');
 
   if (!sprintId || !jsonStr) {
-    console.error('Usage: store-cli.cjs emit <sprintId> \'<json>\' [--sidecar]');
+    console.error('Usage: store-cli.cjs emit <sprintId> \'<json>\' [--sidecar] [--allow-synthetic]');
     process.exit(1);
   }
 
+  // FK check: reject sprintIds that are not in the store and not reserved.
+  // SYS-* prefix is reserved for system-generated events that predate sprint records.
+  // --allow-synthetic bypasses the check for test-harness or synthetic events.
+  if (!allowSynthetic) {
+    const RESERVED_GLOB = /^SYS-/;
+    if (!RESERVED_GLOB.test(sprintId)) {
+      const validSprintIds = resolveValidSprintIds();
+      if (!validSprintIds.includes(sprintId)) {
+        // Suggestion strategy: Levenshtein first; if no results, try suffix match
+        // (e.g., "S01" is a suffix of "FORGE-S01") which Levenshtein alone misses
+        // when the prefix distance exceeds maxDist=2.
+        let suggestions = suggest(sprintId, validSprintIds);
+        if (suggestions.length === 0) {
+          const lower = sprintId.toLowerCase();
+          const suffixMatch = validSprintIds.filter(v => v.toLowerCase().endsWith(lower) || v.toLowerCase().endsWith('-' + lower));
+          if (suffixMatch.length > 0) suggestions = suffixMatch.slice(0, 3);
+        }
+        const hint = formatSuggestion(suggestions);
+        console.error(`Unknown sprintId: ${sprintId}.${hint ? ' ' + hint : ''}`);
+        console.error(`Valid sprint IDs: ${validSprintIds.join(', ') || '(none found)'}`);
+        process.exit(1);
+      }
+    }
+  }
+
   let data;
   try {
     data = JSON.parse(jsonStr);
@@ -1095,12 +1205,12 @@ function cmdValidate() {
   const jsonStr = args[2];
 
   if (!entity || !jsonStr) {
-    console.error('Usage: store-cli.cjs validate <entity> \'<json>\'');
+    console.error('Usage: store-cli.cjs validate \u003centity\u003e \'\u003cjson\u003e\'');
     process.exit(1);
   }
 
   if (!ENTITY_TYPES.includes(entity)) {
-    console.error(`Unknown entity type: ${entity}`);
+    console.error(`Unknown entity type: ${entity}${formatSuggestion(suggestEntityType(entity))}`);
     process.exit(1);
   }
 
@@ -1175,6 +1285,58 @@ function _setSummaryOnEntity(entityKind, entityId, phase, summaryFilePath) {
   if (VERBOSE) console.log(JSON.stringify({ ok: true, entityKind, id: entityId, phase, dryRun: DRY_RUN }));
 }
 
+// ---------------------------------------------------------------------------
+// Summary read-through commands (FORGE-S22-T02)
+//
+// `get-summary <taskId> <phase> [--json]` and `get-bug-summary <bugId> <phase>
+// [--json]` extract a single phase summary from a task/bug record. Registered
+// as direct switch cases (NOT via ALIAS_MAP) so they cannot accidentally
+// route through a write verb (e.g. set-bug-summary).
+// ---------------------------------------------------------------------------
+function _readSummary(entityKind, id, phase, asJson) {
+  const record = entityKind === 'task' ? store.getTask(id) : store.getBug(id);
+  if (!record) {
+    console.error(`error: ${entityKind} ${id} not found`);
+    process.exit(1);
+  }
+  const summary = record.summaries && record.summaries[phase];
+  if (summary === undefined || summary === null) {
+    console.error(`error: no summary for phase '${phase}' on ${entityKind} ${id}`);
+    process.exit(1);
+  }
+  if (asJson) {
+    console.log(JSON.stringify({ entityId: id, phase, summary }, null, 2));
+  } else {
+    if (typeof summary === 'string') {
+      console.log(summary);
+    } else {
+      console.log(JSON.stringify(summary, null, 2));
+    }
+  }
+}
+
+function cmdGetSummary() {
+  const taskId = args[1];
+  const phase  = args[2];
+  const asJson = args.includes('--json');
+  if (!taskId || !phase) {
+    console.error('Usage: store-cli.cjs get-summary <taskId> <phase> [--json]');
+    process.exit(1);
+  }
+  _readSummary('task', taskId, phase, asJson);
+}
+
+function cmdGetBugSummary() {
+  const bugId = args[1];
+  const phase = args[2];
+  const asJson = args.includes('--json');
+  if (!bugId || !phase) {
+    console.error('Usage: store-cli.cjs get-bug-summary <bugId> <phase> [--json]');
+    process.exit(1);
+  }
+  _readSummary('bug', bugId, phase, asJson);
+}
+
 function cmdSetSummary() {
   const taskId      = args[1];
   const phase       = args[2];
@@ -1219,7 +1381,7 @@ function cmdDescribe() {
     process.exit(1);
   }
   if (!VALID_ENTITY_DESCRIBE.has(entity)) {
-    console.error(`Unknown entity: ${entity}`);
+    console.error(`Unknown entity: ${entity}${formatSuggestion(suggestEntityType(entity, Array.from(VALID_ENTITY_DESCRIBE)))}`);
     console.error(`Entities: ${Array.from(VALID_ENTITY_DESCRIBE).join(', ')}`);
     process.exit(1);
   }
@@ -1287,7 +1449,7 @@ function cmdTemplate() {
     process.exit(1);
   }
   if (!VALID_ENTITY_DESCRIBE.has(entity)) {
-    console.error(`Unknown entity: ${entity}`);
+    console.error(`Unknown entity: ${entity}${formatSuggestion(suggestEntityType(entity, Array.from(VALID_ENTITY_DESCRIBE)))}`);
     console.error(`Entities: ${Array.from(VALID_ENTITY_DESCRIBE).join(', ')}`);
     process.exit(1);
   }
@@ -1321,6 +1483,8 @@ switch (command) {
   case 'progress-clear':       cmdProgressClear(); break;
   case 'set-summary':          cmdSetSummary(); break;
   case 'set-bug-summary':      cmdSetBugSummary(); break;
+  case 'get-summary':          cmdGetSummary(); break;
+  case 'get-bug-summary':      cmdGetBugSummary(); break;
   case 'describe':             cmdDescribe(); break;
   case 'template':             cmdTemplate(); break;
   case 'query':
@@ -1336,10 +1500,20 @@ switch (command) {
     process.exit(result.status ?? 1);
     break;
   }
-  default:
-    console.error(`Unknown command: ${command}`);
+  default: {
+    // Build candidate pool: all command names + ALIAS_MAP keys
+    const commandCandidates = [
+      'write', 'read', 'list', 'delete', 'update-status', 'emit', 'merge-sidecar',
+      'record-usage', 'purge-events', 'resolve-event', 'write-collation-state',
+      'validate', 'progress', 'progress-clear', 'set-summary', 'set-bug-summary',
+      'get-summary', 'get-bug-summary', 'describe', 'template', 'query', 'nlp', 'schema',
+      ...Object.keys(ALIAS_MAP)
+    ];
+    const cmdSuggestions = suggest(command, commandCandidates);
+    console.error(`Unknown command: ${command}${formatSuggestion(cmdSuggestions)}`);
     console.error('Run with --help for usage information.');
     process.exit(1);
+  }
 }
 
 } catch (err) {

package/dist/forge-payload/tools/validate-store.cjs

@@ -274,13 +274,15 @@ const DRY_RUN = process.argv.includes('--dry-run');
 const FIX_MODE = process.argv.includes('--fix');
 const JSON_MODE = process.argv.includes('--json');
 
-// Read engineering root and project prefix from config for filesystem consistency checks
+// Read engineering root, store root, and project prefix from config for filesystem consistency checks
 const CONFIG_PATH = '.forge/config.json';
 let engineeringRoot = 'engineering';
+let storeRootFromConfig = '.forge/store';
 let projectPrefix = '[A-Z]+';
 try {
   const cfg = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf8'));
   if (cfg.paths && cfg.paths.engineering) engineeringRoot = cfg.paths.engineering;
+  if (cfg.paths && cfg.paths.store) storeRootFromConfig = cfg.paths.store;
   if (cfg.project && cfg.project.prefix) projectPrefix = cfg.project.prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 } catch (_) {}
 
@@ -490,6 +492,25 @@ for (const sprint of allSprints) {
   }
 }
 
+// --- Pass 2b: Orphan event directories ---
+// Scan .forge/store/events/ for subdirectories whose name does not match any
+// known sprintId and is not a reserved SYS-* prefix.
+const RESERVED_EVENT_PREFIX = /^SYS-/;
+const eventsBaseDir = path.join(storeRootFromConfig, 'events');
+if (fs.existsSync(eventsBaseDir)) {
+  let eventDirEntries;
+  try { eventDirEntries = fs.readdirSync(eventsBaseDir); } catch (_) { eventDirEntries = []; }
+  for (const entry of eventDirEntries) {
+    if (RESERVED_EVENT_PREFIX.test(entry)) continue;  // reserved prefix — skip
+    if (sprintIds.has(entry)) continue;                // known sprint — skip
+    const entryPath = path.join(eventsBaseDir, entry);
+    let isDir = false;
+    try { isDir = fs.statSync(entryPath).isDirectory(); } catch (_) {}
+    if (!isDir) continue;  // non-directory entries — skip silently
+    warn(entry, `event directory "${entry}" has no matching sprint record (ORPHAN_EVENT_DIR)`, 'ORPHAN_EVENT_DIR');
+  }
+}
+
 // --- Pass 3: Filesystem consistency ---
 // Walk engineering/sprints/ to detect orphaned directories and dangling path fields.
 // All checks here emit warnings (not errors) for backward compatibility.

package/node_modules/@aws-sdk/client-bedrock-runtime/dist-cjs/endpoint/endpointResolver.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.defaultEndpointResolver = void 0;
-const util_endpoints_1 = require("@aws-sdk/util-endpoints");
+const client_1 = require("@aws-sdk/core/client");
 const endpoints_1 = require("@smithy/core/endpoints");
 const bdd_1 = require("./bdd");
 const cache = new endpoints_1.EndpointCache({
@@ -15,4 +15,4 @@ const defaultEndpointResolver = (endpointParams, context = {}) => {
     }));
 };
 exports.defaultEndpointResolver = defaultEndpointResolver;
-endpoints_1.customEndpointFunctions.aws = util_endpoints_1.awsEndpointFunctions;
+endpoints_1.customEndpointFunctions.aws = client_1.awsEndpointFunctions;