@entelligentsia/forgecli 0.7.9 → 0.8.4

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

@@ -0,0 +1,1226 @@
+#!/usr/bin/env node
+'use strict';
+
+// Forge tool: store-cli
+// Deterministic store custodian CLI — wraps store.cjs facade.
+// Enforces schema validation on write and status transition rules.
+// Usage: node store-cli.cjs <command> <args>
+
+let _store;
+function _getStore() { return _store || (_store = require('./store.cjs')); }
+let _projectRoot;
+function _getProjectRoot() { return _projectRoot || (_projectRoot = require('./lib/project-root.cjs').findProjectRoot()); }
+
+const _path = require('path');
+
+// Path traversal guard — resolves the events directory and validates that
+// sprintOrBugId doesn't escape it. Same pattern as store.cjs purgeEvents.
+function _resolveEventsDir(sprintOrBugId) {
+  const root = _getProjectRoot();
+  const eventsBase = root
+    ? _path.resolve(root, '.forge', 'store', 'events')
+    : _path.resolve('.forge', 'store', 'events');
+  const resolvedDir = _path.resolve(eventsBase, sprintOrBugId);
+  if (!resolvedDir.startsWith(eventsBase + _path.sep) && resolvedDir !== eventsBase) {
+    console.error(`Path traversal blocked: '${sprintOrBugId}' resolves outside events directory`);
+    process.exit(1);
+  }
+  return resolvedDir;
+}
+
+let _schemas;
+function _getSchemas() {
+  if (_schemas) return _schemas;
+  const fs = require('fs');
+  const path = require('path');
+
+  const ENTITY_TYPES = ['sprint', 'task', 'bug', 'event', 'feature'];
+
+  const MINIMAL_REQUIRED = {
+    sprint:  ['sprintId', 'title', 'status', 'taskIds', 'createdAt'],
+    task:    ['taskId', 'sprintId', 'title', 'status', 'path'],
+    bug:     ['bugId', 'title', 'severity', 'status', 'path', 'reportedAt'],
+    event:   ['eventId', 'taskId', 'sprintId', 'role', 'action', 'phase', 'iteration', 'startTimestamp', 'endTimestamp', 'durationMinutes', 'model'],
+    feature: ['id', 'title', 'status', 'created_at']
+  };
+
+  const schemas = {};
+  const projectDir   = path.join('.forge', 'schemas');
+  const inTreeDir    = path.join('forge', 'schemas');
+  const pluginDir    = path.join(__dirname, '..', 'schemas');
+
+  const AUX_SCHEMAS = {
+    'event-sidecar':    'event-sidecar.schema.json',
+    'progress-entry':   'progress-entry.schema.json',
+    'collation-state':  'collation-state.schema.json',
+  };
+
+  const allTypes = [...ENTITY_TYPES, ...Object.keys(AUX_SCHEMAS)];
+  for (const type of allTypes) {
+    const schemaFile = AUX_SCHEMAS[type] || `${type}.schema.json`;
+    let schema = null;
+
+    // 1. Try project-installed schemas first
+    const projectPath = path.join(projectDir, schemaFile);
+    try {
+      if (fs.existsSync(projectPath)) {
+        schema = JSON.parse(fs.readFileSync(projectPath, 'utf8'));
+      }
+    } catch (_) {}
+
+    // 2. Fall back to in-tree source schemas (development mode)
+    if (!schema) {
+      const inTreePath = path.join(inTreeDir, schemaFile);
+      try {
+        if (fs.existsSync(inTreePath)) {
+          schema = JSON.parse(fs.readFileSync(inTreePath, 'utf8'));
+        }
+      } catch (_) {}
+    }
+
+    // 3. Fall back to plugin-installed schemas (production mode)
+    //    store-cli.cjs lives at $FORGE_ROOT/tools/, so __dirname/../schemas/
+    //    resolves to $FORGE_ROOT/schemas/ — always correct for installed plugins.
+    if (!schema) {
+      const pluginPath = path.join(pluginDir, schemaFile);
+      try {
+        if (fs.existsSync(pluginPath)) {
+          schema = JSON.parse(fs.readFileSync(pluginPath, 'utf8'));
+        }
+      } catch (_) {}
+    }
+
+    if (schema) {
+      schemas[type] = schema;
+    } else {
+      console.error(`WARN: schema file ${schemaFile} not found, using minimal fallback`);
+      schemas[type] = { type: 'object', required: MINIMAL_REQUIRED[type] || [], properties: {} };
+    }
+  }
+
+  _schemas = schemas;
+  return _schemas;
+}
+
+// ---------------------------------------------------------------------------
+// Schema loading — same resolution as validate-store.cjs
+// ---------------------------------------------------------------------------
+
+const ENTITY_TYPES = ['sprint', 'task', 'bug', 'event', 'feature'];
+
+const MINIMAL_REQUIRED = {
+  sprint:  ['sprintId', 'title', 'status', 'taskIds', 'createdAt'],
+  task:    ['taskId', 'sprintId', 'title', 'status', 'path'],
+  bug:     ['bugId', 'title', 'severity', 'status', 'path', 'reportedAt'],
+  event:   ['eventId', 'taskId', 'sprintId', 'role', 'action', 'phase', 'iteration', 'startTimestamp', 'endTimestamp', 'durationMinutes', 'model'],
+  feature: ['id', 'title', 'status', 'created_at']
+};
+
+// Shared validator + nullable-field set live in ./lib/validate.js so the
+// write-boundary hook can reuse the exact same validation logic as tool writes.
+const { validateRecord, NULLABLE_FIELDS } = require('./lib/validate.js');
+
+// Valid phase keys for summaries (dot-delimited → underscore in JSON key)
+const VALID_SUMMARY_PHASES = new Set(['plan', 'review_plan', 'implementation', 'code_review', 'validation']);
+
+// Schema for a single phase summary (used by set-summary / set-bug-summary)
+const PHASE_SUMMARY_SCHEMA = {
+  type: 'object',
+  required: ['objective', 'written_at'],
+  properties: {
+    objective:   { type: 'string', maxLength: 280 },
+    key_changes: { type: 'array', items: { type: 'string', maxLength: 200 }, maxItems: 12 },
+    findings:    { type: 'array', items: { type: 'string', maxLength: 200 }, maxItems: 12 },
+    verdict:     { type: 'string', enum: ['approved', 'revision', 'n/a'] },
+    written_at:  { type: 'string' },
+    artifact_ref:{ type: 'string' }
+  },
+  additionalProperties: false
+};
+
+// validateRecord imported from ./lib/validate.js above.
+
+// ---------------------------------------------------------------------------
+// Transition tables
+// ---------------------------------------------------------------------------
+
+const TASK_TRANSITIONS = {
+  draft:                 ['planned', 'plan-revision-required', 'code-revision-required', 'blocked', 'escalated', 'abandoned'],
+  planned:               ['plan-approved', 'plan-revision-required', 'code-revision-required', 'blocked', 'escalated', 'abandoned'],
+  'plan-approved':       ['implementing', 'plan-revision-required', 'code-revision-required', 'blocked', 'escalated', 'abandoned'],
+  implementing:          ['implemented', 'plan-revision-required', 'code-revision-required', 'blocked', 'escalated', 'abandoned'],
+  implemented:           ['review-approved', 'plan-revision-required', 'code-revision-required', 'blocked', 'escalated', 'abandoned'],
+  'review-approved':     ['approved', 'plan-revision-required', 'code-revision-required', 'blocked', 'escalated', 'abandoned'],
+  approved:              ['committed', 'plan-revision-required', 'code-revision-required', 'blocked', 'escalated', 'abandoned'],
+  // Terminal: committed, abandoned — no transitions out
+};
+
+const SPRINT_TRANSITIONS = {
+  planning:    ['active', 'blocked', 'partially-completed', 'abandoned'],
+  active:      ['completed', 'blocked', 'partially-completed', 'abandoned'],
+  completed:   ['retrospective-done', 'blocked', 'partially-completed', 'abandoned'],
+  // Terminal: retrospective-done, abandoned
+};
+
+const BUG_TRANSITIONS = {
+  reported:     ['triaged'],
+  triaged:      ['in-progress'],
+  'in-progress': ['fixed'],
+  fixed:        ['verified'],
+  // Terminal: verified
+};
+
+const FEATURE_TRANSITIONS = {
+  draft:   ['active'],
+  active:  ['shipped', 'retired'],
+  // Terminal: shipped, retired
+};
+
+const TRANSITION_MAP = {
+  task:    TASK_TRANSITIONS,
+  sprint:  SPRINT_TRANSITIONS,
+  bug:     BUG_TRANSITIONS,
+  feature: FEATURE_TRANSITIONS
+};
+
+const TERMINAL_STATES = new Set([
+  'committed', 'abandoned',          // task
+  'retrospective-done',              // sprint
+  'verified',                        // bug
+  'shipped', 'retired'               // feature
+]);
+
+// Failed states that may be entered from any non-terminal state
+const FAILED_STATES = new Set([
+  'plan-revision-required', 'code-revision-required', 'blocked', 'escalated', 'abandoned',  // task
+  'blocked', 'partially-completed'  // sprint
+]);
+
+function isLegalTransition(entityType, field, currentValue, newValue) {
+  if (currentValue === newValue) return true; // no-op
+
+  const table = TRANSITION_MAP[entityType];
+  if (!table) return true; // no transition rules for this entity type
+
+  // Terminal states cannot transition out
+  if (TERMINAL_STATES.has(currentValue)) return false;
+
+  // Failed states may be entered from any non-terminal state
+  if (FAILED_STATES.has(newValue)) return true;
+
+  // Check the explicit transition table
+  const allowed = table[currentValue];
+  if (!allowed) return false; // current state not in table (unknown state)
+
+  return allowed.includes(newValue);
+}
+
+// ---------------------------------------------------------------------------
+// Bug timestamp normalization helpers
+// ---------------------------------------------------------------------------
+
+// Returns true if the string is a date-only value (YYYY-MM-DD without time).
+// These are rejected by the date-time format validator but agents commonly
+// supply them for reportedAt/resolvedAt.
+function _isDateOnly(ts) {
+  return typeof ts === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(ts);
+}
+
+// Convert a date-only string (YYYY-MM-DD) into a full ISO datetime by
+// appending the current time-of-day in UTC. The date portion is preserved
+// from the input; only the time component is auto-populated.
+function _dateOnlyToISO(dateStr) {
+  const now = new Date();
+  const timePart = now.toISOString().slice(10);  // e.g. "T14:32:07.123Z"
+  return dateStr + timePart;
+}
+
+// Normalize bug datetime fields before writing. When agents supply date-only
+// values (YYYY-MM-DD) for reportedAt or resolvedAt, auto-populates the time
+// component from the current time-of-day so the value passes date-time format
+// validation. Full ISO datetimes are left untouched.
+function _normalizeBugTimestamps(data) {
+  if (_isDateOnly(data.reportedAt))  data.reportedAt  = _dateOnlyToISO(data.reportedAt);
+  if (_isDateOnly(data.resolvedAt))  data.resolvedAt  = _dateOnlyToISO(data.resolvedAt);
+  return data;
+}
+
+// ---------------------------------------------------------------------------
+// Model discovery
+// ---------------------------------------------------------------------------
+
+// Deterministic model discovery — probes environment variables in priority
+// order to resolve the actual runtime model identifier. Returns "unknown"
+// when no signal is available instead of guessing an Anthropic model name.
+function discoverModel() {
+  const candidates = [
+    process.env.CLAUDE_CODE_SUBAGENT_MODEL,
+    process.env.ANTHROPIC_MODEL,
+    process.env.CLAUDE_MODEL,
+  ];
+  for (const val of candidates) {
+    if (val && val.trim()) return val.trim();
+  }
+  return 'unknown';
+}
+
+module.exports = { isLegalTransition, validateRecord, TRANSITION_MAP, TERMINAL_STATES, FAILED_STATES, ENTITY_TYPES, MINIMAL_REQUIRED, NULLABLE_FIELDS, VALID_SUMMARY_PHASES, PHASE_SUMMARY_SCHEMA, _isDateOnly, _dateOnlyToISO, _normalizeBugTimestamps, discoverModel };
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+if (require.main === module) {
+
+process.on('uncaughtException', (error) => {
+  console.error('Fatal store-cli error:', error);
+  process.exit(1);
+});
+
+try {
+const fs = require('fs');
+const path = require('path');
+const store = _getStore();
+const schemas = _getSchemas();
+
+const DRY_RUN = process.argv.includes('--dry-run');
+const VERBOSE = process.argv.includes('--verbose');
+
+// ---------------------------------------------------------------------------
+// Entity ID field mapping
+// ---------------------------------------------------------------------------
+
+const ENTITY_ID_FIELD = {
+  sprint:  'sprintId',
+  task:    'taskId',
+  bug:     'bugId',
+  event:   'eventId',
+  feature: 'id'
+};
+
+// ---------------------------------------------------------------------------
+// Store accessor mapping
+// ---------------------------------------------------------------------------
+
+function getEntity(entity, id) {
+  switch (entity) {
+    case 'sprint':  return store.getSprint(id);
+    case 'task':    return store.getTask(id);
+    case 'bug':     return store.getBug(id);
+    case 'event':   return store.getEvent(id, null); // needs sprintId separately
+    case 'feature': return store.getFeature(id);
+    default:        return null;
+  }
+}
+
+function writeEntity(entity, data) {
+  switch (entity) {
+    case 'sprint':  return store.writeSprint(data);
+    case 'task':    return store.writeTask(data);
+    case 'bug':     return store.writeBug(data);
+    case 'event':   return store.writeEvent(data.sprintId, data);
+    case 'feature': return store.writeFeature(data);
+  }
+}
+
+function deleteEntity(entity, id) {
+  switch (entity) {
+    case 'sprint':  return store.deleteSprint(id);
+    case 'task':    return store.deleteTask(id);
+    case 'bug':     return store.deleteBug(id);
+    case 'feature': return store.deleteFeature(id);
+    default:
+      console.error(`Unknown entity type: ${entity}`);
+      process.exit(1);
+  }
+}
+
+function listEntities(entity, filter) {
+  switch (entity) {
+    case 'sprint':  return store.listSprints(filter);
+    case 'task':    return store.listTasks(filter);
+    case 'bug':     return store.listBugs(filter);
+    case 'feature': return store.listFeatures(filter);
+    default:
+      console.error(`Unknown entity type: ${entity}`);
+      process.exit(1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Sidecar handling
+// ---------------------------------------------------------------------------
+
+// Canonical event schema token fields
+const CANONICAL_TOKEN_FIELDS = [
+  'inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens',
+  'estimatedCostUSD', 'model', 'durationMinutes', 'startTimestamp', 'endTimestamp',
+  'tokenSource'
+];
+
+// Accepted sidecar fields (includes aliases)
+const SIDECAR_ACCEPTED_FIELDS = new Set([
+  'inputTokens', 'outputTokens', 'cacheReadTokens', 'cacheWriteTokens',
+  'estimatedCostUSD', 'model', 'cost', 'durationMinutes',
+  'startTimestamp', 'endTimestamp', 'cacheCreationTokens',
+  'tokenSource'
+]);
+
+// Alias mapping for sidecar → canonical event
+const SIDECAR_ALIASES = {
+  'cacheCreationTokens': 'cacheWriteTokens',
+  'cost': 'estimatedCostUSD'
+};
+
+function resolveSidecarDir(sprintId) {
+  const storeRoot = store.impl.storeRoot;
+  return path.join(storeRoot, 'events', sprintId);
+}
+
+function sidecarPath(sprintId, eventId) {
+  return path.join(resolveSidecarDir(sprintId), `_${eventId}_usage.json`);
+}
+
+function canonicalEventPath(sprintId, eventId) {
+  return path.join(resolveSidecarDir(sprintId), `${eventId}.json`);
+}
+
+// ---------------------------------------------------------------------------
+// CLI argument parsing
+// ---------------------------------------------------------------------------
+
+const args = process.argv.slice(2);
+
+if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
+  console.log(`Forge Store Custodian CLI
+
+Usage: node store-cli.cjs <command> <args> [--dry-run]
+
+Commands:
+  write <entity> '<json>'                     Write a full entity record
+  read <entity> <id> [--json]                 Read an entity record
+  list <entity> [key=value ...]               List entities with optional filter
+  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)
+  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
+  progress <sprintOrBugId> <agentName> <bannerKey> <status> [detail]
+                                              Append a progress entry to the log
+  progress-clear <sprintOrBugId>              Clear (truncate) the progress log
+  write-collation-state '<json>'             Write COLLATION_STATE.json
+  validate <entity> '<json>'                  Validate against schema without writing
+  set-summary <taskId> <phase> <jsonFile>     Set a phase summary on a task record
+  set-bug-summary <bugId> <phase> <jsonFile>  Set a phase summary on a bug record
+  describe <entity>                           Print the JSON Schema for an entity
+  template <entity>                           Print a canonical sample record (required fields populated)
+
+Entities: sprint, task, bug, event, feature
+Phases (summaries): plan, review_plan, implementation, code_review, validation
+
+Flags:
+  --dry-run    Validate and preview without writing (applies to all write commands)
+  --force      Bypass transition check on update-status (emits warning)
+  --json       Output raw JSON on read (no pretty-print)
+  --sidecar    Write as sidecar file on emit (ephemeral _-prefixed)
+
+Exit codes: 0 on success, 1 on failure`);
+  process.exit(0);
+}
+
+const command = args[0];
+
+// ---------------------------------------------------------------------------
+// Command implementations
+// ---------------------------------------------------------------------------
+
+function cmdWrite() {
+  const entity = args[1];
+  const jsonStr = args[2];
+
+  if (!entity || !jsonStr) {
+    console.error('Usage: store-cli.cjs write <entity> \'<json>\'');
+    process.exit(1);
+  }
+
+  if (!ENTITY_TYPES.includes(entity)) {
+    console.error(`Unknown entity type: ${entity}`);
+    process.exit(1);
+  }
+
+  let data;
+  try {
+    data = JSON.parse(jsonStr);
+  } catch (e) {
+    console.error(`Invalid JSON: ${e.message}`);
+    process.exit(1);
+  }
+
+  // Auto-populate date-only YYYY-MM-DD values in bug datetime fields.
+  // Agents commonly supply date-only values for reportedAt/resolvedAt;
+  // this normalizes them to full ISO datetimes before schema validation.
+  if (entity === 'bug') {
+    _normalizeBugTimestamps(data);
+  }
+
+  const errors = validateRecord(data, schemas[entity], { entity });
+  if (errors.length > 0) {
+    for (const e of errors) console.error(e);
+    process.exit(1);
+  }
+
+  if (DRY_RUN) {
+    console.log(`[dry-run] would write ${entity} ${data[ENTITY_ID_FIELD[entity]]}`);
+  } else {
+    writeEntity(entity, data);
+  }
+  if (VERBOSE) console.log(JSON.stringify({ ok: true, entity, id: data[ENTITY_ID_FIELD[entity]], dryRun: DRY_RUN }));
+}
+
+function cmdRead() {
+  const entity = args[1];
+  const id = args[2];
+  const asJson = args.includes('--json');
+
+  if (!entity || !id) {
+    console.error('Usage: store-cli.cjs read <entity> <id> [--json]');
+    process.exit(1);
+  }
+
+  if (!ENTITY_TYPES.includes(entity)) {
+    console.error(`Unknown entity type: ${entity}`);
+    process.exit(1);
+  }
+
+  // Events need sprintId for lookup — read by eventId with sprintId resolution
+  let record;
+  if (entity === 'event') {
+    // For events, try to find by scanning sprint directories
+    const sprints = store.listSprints();
+    record = null;
+    for (const sprint of sprints) {
+      if (!sprint) continue;
+      const found = store.getEvent(id, sprint.sprintId);
+      if (found) { record = found; break; }
+    }
+  } else {
+    record = getEntity(entity, id);
+  }
+
+  if (!record) {
+    console.error(`Entity not found: ${entity} ${id}`);
+    process.exit(1);
+  }
+
+  if (asJson) {
+    console.log(JSON.stringify(record));
+  } else {
+    console.log(JSON.stringify(record, null, 2));
+  }
+}
+
+function cmdList() {
+  const entity = args[1];
+
+  if (!entity) {
+    console.error('Usage: store-cli.cjs list <entity> [key=value ...]');
+    process.exit(1);
+  }
+
+  if (!ENTITY_TYPES.includes(entity)) {
+    console.error(`Unknown entity type: ${entity}`);
+    process.exit(1);
+  }
+
+  // Parse key=value filter pairs from remaining args
+  const filter = {};
+  for (let i = 2; i < args.length; i++) {
+    const eqIdx = args[i].indexOf('=');
+    if (eqIdx > 0) {
+      const key = args[i].slice(0, eqIdx);
+      const val = args[i].slice(eqIdx + 1);
+      // Try to parse numeric values
+      const num = Number(val);
+      filter[key] = (val !== '' && !isNaN(num) && val === String(num)) ? num : val;
+    }
+  }
+
+  const records = listEntities(entity, Object.keys(filter).length > 0 ? filter : undefined);
+  console.log(JSON.stringify(records, null, 2));
+}
+
+function cmdDelete() {
+  const entity = args[1];
+  const id = args[2];
+
+  if (!entity || !id) {
+    console.error('Usage: store-cli.cjs delete <entity> <id>');
+    process.exit(1);
+  }
+
+  if (!ENTITY_TYPES.includes(entity)) {
+    console.error(`Unknown entity type: ${entity}`);
+    process.exit(1);
+  }
+
+  deleteEntity(entity, id);
+  if (VERBOSE) console.log(JSON.stringify({ ok: true, deleted: `${entity}/${id}` }));
+}
+
+function cmdUpdateStatus() {
+  const entity = args[1];
+  const id = args[2];
+  const field = args[3];
+  const value = args[4];
+  const force = args.includes('--force');
+
+  if (!entity || !id || !field || !value) {
+    console.error('Usage: store-cli.cjs update-status <entity> <id> <field> <value> [--force]');
+    process.exit(1);
+  }
+
+  if (!TRANSITION_MAP[entity]) {
+    console.error(`No transition rules for entity type: ${entity}`);
+    process.exit(1);
+  }
+
+  // Read current record
+  const record = getEntity(entity, id);
+  if (!record) {
+    console.error(`Entity not found: ${entity} ${id}`);
+    process.exit(1);
+  }
+
+  const currentValue = record[field];
+  if (currentValue === undefined) {
+    console.error(`Field "${field}" not found on ${entity} ${id}`);
+    process.exit(1);
+  }
+
+  // Check transition legality
+  if (!force && !isLegalTransition(entity, field, currentValue, value)) {
+    console.error(`Illegal transition: ${entity} ${id} ${field}: ${currentValue} → ${value}`);
+    process.exit(1);
+  }
+
+  if (force && !isLegalTransition(entity, field, currentValue, value)) {
+    console.error(`WARN: --force bypassing illegal transition: ${entity} ${id} ${field}: ${currentValue} → ${value}`);
+  }
+
+  // Apply update and write back
+  if (DRY_RUN) {
+    console.log(`[dry-run] would update ${entity} ${id} ${field}: ${currentValue} → ${value}`);
+  } else {
+    record[field] = value;
+    writeEntity(entity, record);
+  }
+  if (VERBOSE) console.log(JSON.stringify({ ok: true, entity, id, field, from: currentValue, to: value, force, dryRun: DRY_RUN }));
+}
+
+// ---------------------------------------------------------------------------
+// Timestamp normalization helpers (#56)
+// ---------------------------------------------------------------------------
+
+// Returns true if the timestamp string has a zeroed time component (T00:00:00),
+// which indicates the caller provided a date-only value instead of a real
+// time-of-day. Midnight UTC is treated as "not set" for event timing purposes.
+function _isZeroedTimestamp(ts) {
+  if (typeof ts !== 'string') return true;  // null / missing → normalize
+  return /T00:00:00/.test(ts);
+}
+
+// Normalize event timestamps before writing. Replaces any zeroed or absent
+// startTimestamp / endTimestamp with the current real time, then recomputes
+// durationMinutes from the two timestamps so cost reports are accurate.
+function _normalizeEventTimestamps(data) {
+  const now = new Date().toISOString();
+
+  if (_isZeroedTimestamp(data.startTimestamp)) data.startTimestamp = now;
+  if (_isZeroedTimestamp(data.endTimestamp))   data.endTimestamp   = now;
+
+  // Recompute durationMinutes whenever both timestamps are present.
+  if (data.startTimestamp && data.endTimestamp) {
+    const diffMs = new Date(data.endTimestamp) - new Date(data.startTimestamp);
+    data.durationMinutes = Math.max(0, diffMs / 60000);
+  }
+
+  return data;
+}
+
+function cmdEmit() {
+  const sprintId = args[1];
+  const jsonStr = args[2];
+  const isSidecar = args.includes('--sidecar');
+
+  if (!sprintId || !jsonStr) {
+    console.error('Usage: store-cli.cjs emit <sprintId> \'<json>\' [--sidecar]');
+    process.exit(1);
+  }
+
+  let data;
+  try {
+    data = JSON.parse(jsonStr);
+  } catch (e) {
+    console.error(`Invalid JSON: ${e.message}`);
+    process.exit(1);
+  }
+
+  if (isSidecar) {
+    // Write sidecar file — validate against the sidecar schema (eventId +
+    // optional token/cost fields). Full event-shape enforcement happens
+    // on merge into the canonical event.
+    const sidecarErrors = validateRecord(data, schemas['event-sidecar']);
+    if (sidecarErrors.length > 0) {
+      for (const e of sidecarErrors) console.error(e);
+      process.exit(1);
+    }
+
+    const sidecarDir = resolveSidecarDir(sprintId);
+    const filePath = sidecarPath(sprintId, data.eventId);
+
+    if (DRY_RUN) {
+      console.log(`[dry-run] would write sidecar _${data.eventId}_usage.json`);
+    } else {
+      // Ensure directory exists
+      if (!fs.existsSync(sidecarDir)) {
+        fs.mkdirSync(sidecarDir, { recursive: true });
+      }
+
+      fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
+    }
+    if (VERBOSE) console.log(JSON.stringify({ ok: true, sidecar: true, eventId: data.eventId, sprintId, dryRun: DRY_RUN }));
+  } else {
+    // Normalize zeroed timestamps before validation so agents that provide
+    // date-only values (T00:00:00Z) get real time-of-day stamped in (#56).
+    _normalizeEventTimestamps(data);
+
+    // Auto-populate model from environment when missing or empty (FORGE-S12-T06).
+    // Callers who set model explicitly take priority — discoverModel() is only
+    // used as a fallback so we never silently record a wrong model name.
+    if (!data.model || !data.model.trim()) {
+      data.model = discoverModel();
+    }
+
+    // Validate as event entity
+    const errors = validateRecord(data, schemas.event);
+    if (errors.length > 0) {
+      for (const e of errors) console.error(e);
+      process.exit(1);
+    }
+
+    if (DRY_RUN) {
+      console.log(`[dry-run] would emit event ${data.eventId}`);
+    } else {
+      store.writeEvent(sprintId, data);
+    }
+    if (VERBOSE) console.log(JSON.stringify({ ok: true, event: true, eventId: data.eventId, sprintId, dryRun: DRY_RUN }));
+  }
+}
+
+function cmdMergeSidecar() {
+  const sprintId = args[1];
+  const eventId = args[2];
+
+  if (!sprintId || !eventId) {
+    console.error('Usage: store-cli.cjs merge-sidecar <sprintId> <eventId>');
+    process.exit(1);
+  }
+
+  // Read sidecar
+  const scPath = sidecarPath(sprintId, eventId);
+  if (!fs.existsSync(scPath)) {
+    console.error(`Sidecar not found: ${scPath}`);
+    process.exit(1);
+  }
+
+  let sidecar;
+  try {
+    sidecar = JSON.parse(fs.readFileSync(scPath, 'utf8'));
+  } catch (e) {
+    console.error(`Invalid sidecar JSON: ${e.message}`);
+    process.exit(1);
+  }
+
+  // Read canonical event
+  const canPath = canonicalEventPath(sprintId, eventId);
+  if (!fs.existsSync(canPath)) {
+    console.error(`Canonical event not found: ${canPath}`);
+    process.exit(1);
+  }
+
+  let event;
+  try {
+    event = JSON.parse(fs.readFileSync(canPath, 'utf8'));
+  } catch (e) {
+    console.error(`Invalid canonical event JSON: ${e.message}`);
+    process.exit(1);
+  }
+
+  // Merge token fields from sidecar into event
+  for (const [key, value] of Object.entries(sidecar)) {
+    // Resolve aliases
+    const canonicalKey = SIDECAR_ALIASES[key] || key;
+    if (CANONICAL_TOKEN_FIELDS.includes(canonicalKey)) {
+      event[canonicalKey] = value;
+    }
+  }
+
+  // Re-validate the merged canonical event against the event schema. Catches
+  // the case where a sidecar's token field is present but the canonical event
+  // was already malformed — we do not want to silently persist invalid data.
+  const mergedErrors = validateRecord(event, schemas.event);
+  if (mergedErrors.length > 0) {
+    console.error(`Merged event ${eventId} failed schema validation:`);
+    for (const e of mergedErrors) console.error(`  ${e}`);
+    process.exit(1);
+  }
+
+  if (DRY_RUN) {
+    console.log(`[dry-run] would merge sidecar into ${eventId} and delete sidecar`);
+  } else {
+    // Write updated event via facade (handles ghost-file logic)
+    store.writeEvent(sprintId, event);
+
+    // Delete sidecar
+    fs.unlinkSync(scPath);
+  }
+
+  if (VERBOSE) console.log(JSON.stringify({ ok: true, merged: true, eventId, sprintId, dryRun: DRY_RUN }));
+}
+
+function cmdRecordUsage() {
+  const sprintId = args[1];
+  const eventId = args[2];
+
+  if (!sprintId || !eventId) {
+    console.error('Usage: store-cli.cjs record-usage <sprintId> <eventId> [flags]');
+    console.error('  Flags:');
+    console.error('    --input-tokens <n>          Input token count');
+    console.error('    --output-tokens <n>         Output token count');
+    console.error('    --cache-read-tokens <n>     Cache read token count');
+    console.error('    --cache-write-tokens <n>    Cache write token count');
+    console.error('    --estimated-cost-usd <n>     Estimated cost in USD');
+    console.error('    --token-source <src>         reported | estimated');
+    console.error('    --model <model>             Model identifier');
+    console.error('    --duration-minutes <n>      Duration in minutes');
+    process.exit(1);
+  }
+
+  // Parse flag arguments from remaining args
+  const flagArgs = args.slice(3);
+  const sidecar = { eventId };
+
+  for (let i = 0; i < flagArgs.length; i++) {
+    const arg = flagArgs[i];
+    if (arg === '--input-tokens' && flagArgs[i + 1]) {
+      sidecar.inputTokens = parseInt(flagArgs[++i], 10);
+    } else if (arg === '--output-tokens' && flagArgs[i + 1]) {
+      sidecar.outputTokens = parseInt(flagArgs[++i], 10);
+    } else if (arg === '--cache-read-tokens' && flagArgs[i + 1]) {
+      sidecar.cacheReadTokens = parseInt(flagArgs[++i], 10);
+    } else if (arg === '--cache-write-tokens' && flagArgs[i + 1]) {
+      sidecar.cacheWriteTokens = parseInt(flagArgs[++i], 10);
+    } else if (arg === '--estimated-cost-usd' && flagArgs[i + 1]) {
+      sidecar.estimatedCostUSD = parseFloat(flagArgs[++i]);
+    } else if (arg === '--token-source' && flagArgs[i + 1]) {
+      sidecar.tokenSource = flagArgs[++i];
+    } else if (arg === '--model' && flagArgs[i + 1]) {
+      sidecar.model = flagArgs[++i];
+    } else if (arg === '--duration-minutes' && flagArgs[i + 1]) {
+      sidecar.durationMinutes = parseFloat(flagArgs[++i]);
+    }
+  }
+
+  // Auto-populate model from environment when --model flag not provided (FORGE-S12-T06).
+  // An explicit --model flag takes priority — discoverModel() is only a fallback.
+  if (!sidecar.model) {
+    sidecar.model = discoverModel();
+  }
+
+  // Validate against sidecar schema
+  const sidecarErrors = validateRecord(sidecar, schemas['event-sidecar']);
+  if (sidecarErrors.length > 0) {
+    for (const e of sidecarErrors) console.error(e);
+    process.exit(1);
+  }
+
+  const sidecarDir = resolveSidecarDir(sprintId);
+  const filePath = sidecarPath(sprintId, eventId);
+
+  if (DRY_RUN) {
+    console.log(`[dry-run] would write sidecar _${eventId}_usage.json`);
+  } else {
+    if (!fs.existsSync(sidecarDir)) {
+      fs.mkdirSync(sidecarDir, { recursive: true });
+    }
+    fs.writeFileSync(filePath, JSON.stringify(sidecar, null, 2) + '\n', 'utf8');
+  }
+  if (VERBOSE) console.log(JSON.stringify({ ok: true, sidecar: true, eventId, sprintId, dryRun: DRY_RUN }));
+}
+
+function cmdPurgeEvents() {
+  const sprintId = args[1];
+
+  if (!sprintId) {
+    console.error('Usage: store-cli.cjs purge-events <sprintId>');
+    process.exit(1);
+  }
+
+  const result = store.purgeEvents(sprintId, { dryRun: DRY_RUN });
+  if (DRY_RUN && !result.purged) {
+    console.log(`[dry-run] would purge ${result.fileCount} event(s) for ${sprintId}`);
+  }
+  if (VERBOSE) console.log(JSON.stringify(result, null, 2));
+}
+
+function cmdWriteCollationState() {
+  const jsonStr = args[1];
+
+  if (!jsonStr) {
+    console.error('Usage: store-cli.cjs write-collation-state \'<json>\'');
+    process.exit(1);
+  }
+
+  let data;
+  try {
+    data = JSON.parse(jsonStr);
+  } catch (e) {
+    console.error(`Invalid JSON: ${e.message}`);
+    process.exit(1);
+  }
+
+  const csErrors = validateRecord(data, schemas['collation-state']);
+  if (csErrors.length > 0) {
+    for (const e of csErrors) console.error(e);
+    process.exit(1);
+  }
+
+  if (DRY_RUN) {
+    console.log('[dry-run] would write COLLATION_STATE.json');
+  } else {
+    store.writeCollationState(data);
+  }
+  if (VERBOSE) console.log(JSON.stringify({ ok: true, dryRun: DRY_RUN }));
+}
+
+function cmdProgress() {
+  const sprintOrBugId = args[1];
+  const agentName = args[2];
+  const bannerKey = args[3];
+  const status = args[4];
+  const detail = args.slice(5).join(' ');
+
+  if (!sprintOrBugId || !agentName || !bannerKey || !status) {
+    console.error('Usage: store-cli.cjs progress <sprintOrBugId> <agentName> <bannerKey> <status> [detail]');
+    console.error('  status: start | progress | done | error');
+    process.exit(1);
+  }
+
+  const timestamp = new Date().toISOString();
+
+  const progressErrors = validateRecord(
+    { timestamp, agentName, bannerKey, status, detail: detail || '' },
+    schemas['progress-entry']
+  );
+  if (progressErrors.length > 0) {
+    for (const e of progressErrors) console.error(e);
+    process.exit(1);
+  }
+
+  const line = `${timestamp}|${agentName}|${bannerKey}|${status}|${detail}\n`;
+
+  const dir = _resolveEventsDir(sprintOrBugId);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  const logPath = path.join(dir, 'progress.log');
+  fs.appendFileSync(logPath, line, 'utf8');
+
+  // Emit human-readable summary to stdout
+  let banners;
+  try { banners = require('./banners.cjs'); } catch { banners = null; }
+  let emoji = bannerKey;
+  if (banners && typeof banners.mark === 'function') {
+    try { emoji = banners.mark(bannerKey); } catch { emoji = bannerKey; }
+  }
+  const summary = `${emoji}  ${agentName}  [${status}]${detail ? '  ' + detail : ''}`;
+  if (VERBOSE) process.stdout.write(summary + '\n');
+}
+
+function cmdProgressClear() {
+  const sprintOrBugId = args[1];
+
+  if (!sprintOrBugId) {
+    console.error('Usage: store-cli.cjs progress-clear <sprintOrBugId>');
+    process.exit(1);
+  }
+
+  const dir = _resolveEventsDir(sprintOrBugId);
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+
+  const logPath = path.join(dir, 'progress.log');
+  fs.writeFileSync(logPath, '', 'utf8');
+  if (VERBOSE) console.log(`Cleared ${logPath}`);
+}
+
+function cmdValidate() {
+  const entity = args[1];
+  const jsonStr = args[2];
+
+  if (!entity || !jsonStr) {
+    console.error('Usage: store-cli.cjs validate <entity> \'<json>\'');
+    process.exit(1);
+  }
+
+  if (!ENTITY_TYPES.includes(entity)) {
+    console.error(`Unknown entity type: ${entity}`);
+    process.exit(1);
+  }
+
+  let data;
+  try {
+    data = JSON.parse(jsonStr);
+  } catch (e) {
+    console.error(`Invalid JSON: ${e.message}`);
+    process.exit(1);
+  }
+
+  const errors = validateRecord(data, schemas[entity], { entity });
+  if (errors.length > 0) {
+    for (const e of errors) console.error(e);
+    process.exit(1);
+  }
+
+  if (VERBOSE) console.log(JSON.stringify({ ok: true, entity, valid: true }));
+}
+
+function _setSummaryOnEntity(entityKind, entityId, phase, summaryFilePath) {
+  if (!VALID_SUMMARY_PHASES.has(phase)) {
+    console.error(`Unknown phase "${phase}". Valid phases: ${[...VALID_SUMMARY_PHASES].join(', ')}`);
+    process.exit(1);
+  }
+
+  // Read and validate summary JSON
+  if (!fs.existsSync(summaryFilePath)) {
+    console.error(`Summary file not found: ${summaryFilePath}`);
+    process.exit(1);
+  }
+
+  let summary;
+  try {
+    summary = JSON.parse(fs.readFileSync(summaryFilePath, 'utf8'));
+  } catch (e) {
+    console.error(`Invalid JSON in summary file: ${e.message}`);
+    process.exit(1);
+  }
+
+  const errors = validateRecord(summary, PHASE_SUMMARY_SCHEMA);
+  if (errors.length > 0) {
+    for (const e of errors) console.error(e);
+    process.exit(1);
+  }
+
+  // Load entity
+  const record = entityKind === 'task' ? store.getTask(entityId) : store.getBug(entityId);
+  if (!record) {
+    console.error(`${entityKind} not found: ${entityId}`);
+    process.exit(1);
+  }
+
+  // Merge summary
+  if (!record.summaries) record.summaries = {};
+  record.summaries[phase] = summary;
+
+  // Atomic write: tmp + rename
+  const entityDirKey = entityKind === 'task' ? 'tasks' : 'bugs';
+  const idField = entityKind === 'task' ? record.taskId : record.bugId;
+  const storeRoot = store.impl.storeRoot;
+  const filePath = path.join(storeRoot, entityDirKey, `${idField}.json`);
+  const tmpPath = filePath + '.tmp';
+
+  if (DRY_RUN) {
+    console.log(`[dry-run] would set ${entityKind} ${entityId} summaries.${phase}`);
+  } else {
+    fs.writeFileSync(tmpPath, JSON.stringify(record, null, 2) + '\n', 'utf8');
+    fs.renameSync(tmpPath, filePath);
+  }
+
+  if (VERBOSE) console.log(JSON.stringify({ ok: true, entityKind, id: entityId, phase, dryRun: DRY_RUN }));
+}
+
+function cmdSetSummary() {
+  const taskId      = args[1];
+  const phase       = args[2];
+  const summaryFile = args[3];
+
+  if (!taskId || !phase || !summaryFile) {
+    console.error('Usage: store-cli.cjs set-summary <taskId> <phase> <jsonFile>');
+    process.exit(1);
+  }
+
+  _setSummaryOnEntity('task', taskId, phase, summaryFile);
+}
+
+function cmdSetBugSummary() {
+  const bugId       = args[1];
+  const phase       = args[2];
+  const summaryFile = args[3];
+
+  if (!bugId || !phase || !summaryFile) {
+    console.error('Usage: store-cli.cjs set-bug-summary <bugId> <phase> <jsonFile>');
+    process.exit(1);
+  }
+
+  _setSummaryOnEntity('bug', bugId, phase, summaryFile);
+}
+
+// ---------------------------------------------------------------------------
+// describe / template — schema introspection helpers (FORGE-BUG-029-friction)
+//
+// Reduce write→reject→retry friction. `describe <entity>` returns the raw
+// JSON Schema; `template <entity>` walks the schema and returns a canonical
+// sample record with required fields populated.
+// ---------------------------------------------------------------------------
+
+const VALID_ENTITY_DESCRIBE = new Set(['sprint', 'task', 'bug', 'event', 'feature']);
+
+function cmdDescribe() {
+  const entity = args[1];
+  if (!entity) {
+    console.error('Usage: store-cli.cjs describe <entity>');
+    console.error(`Entities: ${Array.from(VALID_ENTITY_DESCRIBE).join(', ')}`);
+    process.exit(1);
+  }
+  if (!VALID_ENTITY_DESCRIBE.has(entity)) {
+    console.error(`Unknown entity: ${entity}`);
+    console.error(`Entities: ${Array.from(VALID_ENTITY_DESCRIBE).join(', ')}`);
+    process.exit(1);
+  }
+  const schema = _getSchemas()[entity];
+  if (!schema) {
+    console.error(`Schema not found for entity: ${entity}`);
+    process.exit(1);
+  }
+  console.log(JSON.stringify(schema, null, 2));
+}
+
+// Field-name → placeholder ID heuristics. Covers the common shapes without
+// inventing schema-specific knowledge in the generator itself.
+function _idPlaceholder(entity, fieldName) {
+  if (fieldName === 'sprintId')   return 'PROJECT-S01';
+  if (fieldName === 'taskId')     return 'PROJECT-S01-T01';
+  if (fieldName === 'bugId')      return 'PROJECT-BUG-001';
+  if (fieldName === 'feature_id' || fieldName === 'featureId') return 'PROJECT-F01';
+  if (fieldName === 'eventId')    return '20260101T000000000Z_PROJECT-S01-T01_phase_start';
+  if (entity === 'feature' && fieldName === 'id') return 'PROJECT-F01';
+  return `<${fieldName}>`;
+}
+
+function _generateSample(schema, entity) {
+  const sample = {};
+  const required = schema.required || [];
+  const properties = schema.properties || {};
+  for (const field of required) {
+    const def = properties[field] || {};
+    sample[field] = _generateValue(def, field, entity);
+  }
+  return sample;
+}
+
+function _generateValue(def, fieldName, entity) {
+  // Resolve type — handle union (array of types) by picking the first non-null.
+  let t = def.type;
+  if (Array.isArray(t)) t = t.find((x) => x !== 'null') || t[0];
+
+  if (def.enum && Array.isArray(def.enum) && def.enum.length > 0) {
+    return def.enum[0];
+  }
+  if (t === 'string') {
+    if (def.format === 'date-time') return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+    if (/Id$|^id$/.test(fieldName) || fieldName === 'feature_id' || fieldName === 'eventId') {
+      return _idPlaceholder(entity, fieldName);
+    }
+    if (fieldName === 'title')       return 'Sample title';
+    if (fieldName === 'description') return 'Sample description';
+    if (fieldName === 'path')        return `engineering/sprints/PROJECT-S01/${fieldName}-sample.md`;
+    return `<${fieldName}>`;
+  }
+  if (t === 'integer' || t === 'number') return 0;
+  if (t === 'boolean') return false;
+  if (t === 'array') return [];
+  if (t === 'object') return {};
+  return null;
+}
+
+function cmdTemplate() {
+  const entity = args[1];
+  if (!entity) {
+    console.error('Usage: store-cli.cjs template <entity>');
+    console.error(`Entities: ${Array.from(VALID_ENTITY_DESCRIBE).join(', ')}`);
+    process.exit(1);
+  }
+  if (!VALID_ENTITY_DESCRIBE.has(entity)) {
+    console.error(`Unknown entity: ${entity}`);
+    console.error(`Entities: ${Array.from(VALID_ENTITY_DESCRIBE).join(', ')}`);
+    process.exit(1);
+  }
+  const schema = _getSchemas()[entity];
+  if (!schema) {
+    console.error(`Schema not found for entity: ${entity}`);
+    process.exit(1);
+  }
+  const sample = _generateSample(schema, entity);
+  console.log(JSON.stringify(sample, null, 2));
+}
+
+// ---------------------------------------------------------------------------
+// Command dispatch
+// ---------------------------------------------------------------------------
+
+switch (command) {
+  case 'write':                cmdWrite(); break;
+  case 'read':                 cmdRead(); break;
+  case 'list':                 cmdList(); break;
+  case 'delete':               cmdDelete(); break;
+  case 'update-status':        cmdUpdateStatus(); break;
+  case 'emit':                 cmdEmit(); break;
+  case 'merge-sidecar':        cmdMergeSidecar(); break;
+  case 'record-usage':        cmdRecordUsage(); break;
+  case 'purge-events':         cmdPurgeEvents(); break;
+  case 'write-collation-state': cmdWriteCollationState(); break;
+  case 'validate':             cmdValidate(); break;
+  case 'progress':             cmdProgress(); break;
+  case 'progress-clear':       cmdProgressClear(); break;
+  case 'set-summary':          cmdSetSummary(); break;
+  case 'set-bug-summary':      cmdSetBugSummary(); break;
+  case 'describe':             cmdDescribe(); break;
+  case 'template':             cmdTemplate(); break;
+  case 'query':
+  case 'nlp':
+  case 'schema': {
+    // Delegate to store-query.cjs — query engine lives there
+    const { spawnSync } = require('child_process');
+    const queryBin = path.join(__dirname, 'store-query.cjs');
+    const result = spawnSync(process.execPath, [queryBin, command, ...args.slice(1)], {
+      stdio: 'inherit',
+      cwd: process.cwd(),
+    });
+    process.exit(result.status ?? 1);
+    break;
+  }
+  default:
+    console.error(`Unknown command: ${command}`);
+    console.error('Run with --help for usage information.');
+    process.exit(1);
+}
+
+} catch (err) {
+  console.error(err.message);
+  process.exit(1);
+}
+
+} // end if (require.main === module)