scene-capability-engine 3.3.25 → 3.3.26

package/CHANGELOG.md

@@ -14,6 +14,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - New script gate:
   - `node scripts/errorbook-registry-health-gate.js`
   - supports strict mode via `SCE_REGISTRY_HEALTH_STRICT=1`
+- Local project timeline snapshot system:
+  - new command group: `sce timeline ...`
+  - supports manual save/list/show/restore/config and `timeline push` (pre-push checkpoint + git push)
+  - snapshots are retained under `.sce/timeline/snapshots/` with configurable retention policy
+  - key-stage checkpoint integration for `studio` and `session` command flows
 
 ### Changed
 - `prepublishOnly` now runs `gate:errorbook-registry-health` in advisory mode before `errorbook-release` gate.
@@ -46,6 +51,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - new command: `sce spec-related` (alias route: `sce spec related`)
   - supports query/scene/spec-seeded lookup and relevance ranking
   - `sce studio plan` now auto-loads related historical specs into job metadata (`source.related_specs`)
+- SCE now captures timeline checkpoints by default on `studio`/`session` key operations, and performs interval auto-check in the same checkpoint pipeline to reduce local history-loss risk.
 
 ## [3.3.23] - 2026-02-27
 

package/bin/scene-capability-engine.js

@@ -21,6 +21,7 @@ const { registerSpecPipelineCommand } = require('../lib/commands/spec-pipeline')
 const { registerSpecGateCommand } = require('../lib/commands/spec-gate');
 const { registerSpecDomainCommand } = require('../lib/commands/spec-domain');
 const { registerSpecRelatedCommand } = require('../lib/commands/spec-related');
+const { registerTimelineCommands } = require('../lib/commands/timeline');
 const { registerValueCommands } = require('../lib/commands/value');
 const VersionChecker = require('../lib/version/version-checker');
 const {
@@ -820,6 +821,7 @@ registerCollabCommands(program);
 // Universal steering and runtime session commands
 registerSteeringCommands(program);
 registerSessionCommands(program);
+registerTimelineCommands(program);
 
 // Autonomous control commands
 const { registerAutoCommands } = require('../lib/commands/auto');

package/docs/command-reference.md

@@ -2,7 +2,7 @@
 
 > Quick reference for all `sce` commands
 
-**Version**: 3.3.23
+**Version**: 3.3.25
 **Last Updated**: 2026-02-27
 
 ---
@@ -96,6 +96,37 @@ Spec session governance:
   - `.sce/specs/<spec>/custom/scene-spec.md`
   - `.sce/specs/<spec>/custom/problem-domain-chain.json`
 
+### Timeline Snapshots
+
+```bash
+# Manual checkpoint
+sce timeline save --summary "before large refactor" --json
+
+# Auto interval checkpoint tick (skips when interval is not reached)
+sce timeline auto --json
+
+# List and inspect snapshots
+sce timeline list --limit 20 --json
+sce timeline show <snapshot-id> --json
+
+# Restore workspace to a snapshot (safe mode keeps extra files)
+sce timeline restore <snapshot-id> --json
+
+# Hard restore (also prune files not in snapshot)
+sce timeline restore <snapshot-id> --prune --json
+
+# Update timeline policy
+sce timeline config --enabled true --interval 30 --max-entries 120 --json
+
+# Push with pre-push snapshot
+sce timeline push origin main
+```
+
+Timeline policy:
+- default enabled with local retention under `.sce/timeline/snapshots/`
+- stage/key-event checkpoints are automatically captured for `studio` and `session` commands
+- interval auto-checkpoints are integrated in the same flow via timeline checkpoint capture
+
 ### Value Metrics
 
 ```bash

package/lib/commands/session.js

@@ -1,5 +1,6 @@
 const chalk = require('chalk');
 const { SessionStore } = require('../runtime/session-store');
+const { captureTimelineCheckpoint } = require('../runtime/project-timeline');
 
 function registerSessionCommands(program) {
   const session = program
@@ -15,6 +16,14 @@ function registerSessionCommands(program) {
     .option('--json', 'Output as JSON')
     .action(async (objective, options) => {
       try {
+        await captureTimelineCheckpoint({
+          trigger: 'key-event',
+          event: 'session.start',
+          summary: `session start | tool=${options.tool || 'generic'} | objective=${objective || ''}`.trim(),
+          command: 'sce session start'
+        }, {
+          projectPath: process.cwd()
+        });
         const store = new SessionStore(process.cwd());
         const created = await store.startSession({
           tool: options.tool,
@@ -35,6 +44,15 @@ function registerSessionCommands(program) {
     .option('--json', 'Output as JSON')
     .action(async (sessionRef, options) => {
       try {
+        await captureTimelineCheckpoint({
+          trigger: 'key-event',
+          event: 'session.resume',
+          summary: `session resume | ref=${sessionRef || 'latest'} | status=${options.status || 'active'}`,
+          command: 'sce session resume',
+          sessionId: sessionRef || 'latest'
+        }, {
+          projectPath: process.cwd()
+        });
         const store = new SessionStore(process.cwd());
         const resumed = await store.resumeSession(sessionRef || 'latest', {
           status: options.status,
@@ -54,6 +72,15 @@ function registerSessionCommands(program) {
     .option('--json', 'Output as JSON')
     .action(async (sessionRef, options) => {
       try {
+        await captureTimelineCheckpoint({
+          trigger: 'key-event',
+          event: 'session.snapshot',
+          summary: `session snapshot | ref=${sessionRef || 'latest'} | status=${options.status || 'inherit'}`,
+          command: 'sce session snapshot',
+          sessionId: sessionRef || 'latest'
+        }, {
+          projectPath: process.cwd()
+        });
         const store = new SessionStore(process.cwd());
         const payload = _parsePayload(options.payload);
         const snapshotted = await store.snapshotSession(sessionRef || 'latest', {

package/lib/commands/studio.js

@@ -9,6 +9,7 @@ const {
   ensureSpecDomainArtifacts
 } = require('../spec/domain-modeling');
 const { findRelatedSpecs } = require('../spec/related-specs');
+const { captureTimelineCheckpoint } = require('../runtime/project-timeline');
 
 const STUDIO_JOB_API_VERSION = 'sce.studio.job/v0.1';
 const STAGE_ORDER = ['plan', 'generate', 'apply', 'verify', 'release'];
@@ -1636,8 +1637,30 @@ async function runStudioEventsCommand(options = {}, dependencies = {}) {
   return payload;
 }
 
-async function runStudioCommand(handler, options) {
+async function runStudioCommand(handler, options, stageName = '') {
   try {
+    const stage = normalizeString(stageName) || 'unknown';
+    const sceneId = normalizeString(options && options.scene);
+    const summaryGoal = normalizeString(options && options.goal);
+    const fromChat = normalizeString(options && options.fromChat);
+    const summaryParts = [
+      'studio',
+      stage,
+      sceneId ? `scene=${sceneId}` : '',
+      summaryGoal ? `goal=${summaryGoal}` : '',
+      fromChat ? `chat=${fromChat}` : ''
+    ].filter(Boolean);
+
+    await captureTimelineCheckpoint({
+      trigger: 'key-event',
+      event: `studio.${stage}`,
+      summary: summaryParts.join(' | '),
+      command: `sce studio ${stage}`.trim(),
+      sceneId
+    }, {
+      projectPath: process.cwd()
+    });
+
     await handler(options);
   } catch (error) {
     console.error(chalk.red(`Studio command failed: ${error.message}`));
@@ -1660,7 +1683,7 @@ function registerStudioCommands(program) {
     .option('--target <target>', 'Target integration profile', 'default')
     .option('--job <job-id>', 'Reuse an explicit studio job id')
     .option('--json', 'Print machine-readable JSON output')
-    .action(async (options) => runStudioCommand(runStudioPlanCommand, options));
+    .action(async (options) => runStudioCommand(runStudioPlanCommand, options, 'plan'));
 
   studio
     .command('generate')
@@ -1670,7 +1693,7 @@ function registerStudioCommands(program) {
     .option('--patch-bundle <id>', 'Explicit patch bundle id')
     .option('--job <job-id>', 'Studio job id (defaults to latest)')
     .option('--json', 'Print machine-readable JSON output')
-    .action(async (options) => runStudioCommand(runStudioGenerateCommand, options));
+    .action(async (options) => runStudioCommand(runStudioGenerateCommand, options, 'generate'));
 
   studio
     .command('apply')
@@ -1680,7 +1703,7 @@ function registerStudioCommands(program) {
     .option('--require-auth', 'Require authorization even when policy is advisory')
     .option('--job <job-id>', 'Studio job id (defaults to latest)')
     .option('--json', 'Print machine-readable JSON output')
-    .action(async (options) => runStudioCommand(runStudioApplyCommand, options));
+    .action(async (options) => runStudioCommand(runStudioApplyCommand, options, 'apply'));
 
   studio
     .command('verify')
@@ -1688,7 +1711,7 @@ function registerStudioCommands(program) {
     .option('--profile <profile>', 'Verification profile', 'standard')
     .option('--job <job-id>', 'Studio job id (defaults to latest)')
     .option('--json', 'Print machine-readable JSON output')
-    .action(async (options) => runStudioCommand(runStudioVerifyCommand, options));
+    .action(async (options) => runStudioCommand(runStudioVerifyCommand, options, 'verify'));
 
   studio
     .command('release')
@@ -1700,14 +1723,14 @@ function registerStudioCommands(program) {
     .option('--release-ref <ref>', 'Explicit release reference/tag')
     .option('--job <job-id>', 'Studio job id (defaults to latest)')
     .option('--json', 'Print machine-readable JSON output')
-    .action(async (options) => runStudioCommand(runStudioReleaseCommand, options));
+    .action(async (options) => runStudioCommand(runStudioReleaseCommand, options, 'release'));
 
   studio
     .command('resume')
     .description('Inspect current studio job and next action')
     .option('--job <job-id>', 'Studio job id (defaults to latest)')
     .option('--json', 'Print machine-readable JSON output')
-    .action(async (options) => runStudioCommand(runStudioResumeCommand, options));
+    .action(async (options) => runStudioCommand(runStudioResumeCommand, options, 'resume'));
 
   studio
     .command('events')
@@ -1715,7 +1738,7 @@ function registerStudioCommands(program) {
     .option('--job <job-id>', 'Studio job id (defaults to latest)')
     .option('--limit <number>', 'Maximum number of recent events to return', '50')
     .option('--json', 'Print machine-readable JSON output')
-    .action(async (options) => runStudioCommand(runStudioEventsCommand, options));
+    .action(async (options) => runStudioCommand(runStudioEventsCommand, options, 'events'));
 
   studio
     .command('rollback')
@@ -1725,7 +1748,7 @@ function registerStudioCommands(program) {
     .option('--auth-password <password>', 'Authorization password for protected rollback action')
     .option('--require-auth', 'Require authorization even when policy is advisory')
     .option('--json', 'Print machine-readable JSON output')
-    .action(async (options) => runStudioCommand(runStudioRollbackCommand, options));
+    .action(async (options) => runStudioCommand(runStudioRollbackCommand, options, 'rollback'));
 }
 
 module.exports = {

package/lib/commands/timeline.js

@@ -0,0 +1,287 @@
+const { spawnSync } = require('child_process');
+const chalk = require('chalk');
+const fs = require('fs-extra');
+const {
+  ProjectTimelineStore,
+  captureTimelineCheckpoint
+} = require('../runtime/project-timeline');
+
+function normalizeText(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+function normalizePositiveInteger(value, fallback, max = 10000) {
+  const parsed = Number.parseInt(`${value}`, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return fallback;
+  }
+  return Math.min(parsed, max);
+}
+
+function normalizeBoolean(value, fallback = false) {
+  if (typeof value === 'boolean') {
+    return value;
+  }
+  const normalized = normalizeText(`${value || ''}`).toLowerCase();
+  if (!normalized) {
+    return fallback;
+  }
+  if (['1', 'true', 'yes', 'y', 'on'].includes(normalized)) {
+    return true;
+  }
+  if (['0', 'false', 'no', 'n', 'off'].includes(normalized)) {
+    return false;
+  }
+  return fallback;
+}
+
+function createStore(dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  return dependencies.timelineStore || new ProjectTimelineStore(projectPath, fileSystem);
+}
+
+function printPayload(payload, asJson = false, title = 'Timeline') {
+  if (asJson) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  console.log(chalk.blue(title));
+  if (payload.mode) {
+    console.log(`  Mode: ${payload.mode}`);
+  }
+  if (payload.snapshot && payload.snapshot.snapshot_id) {
+    console.log(`  Snapshot: ${payload.snapshot.snapshot_id}`);
+  }
+  if (payload.snapshot_id) {
+    console.log(`  Snapshot: ${payload.snapshot_id}`);
+  }
+  if (payload.restored_from) {
+    console.log(`  Restored From: ${payload.restored_from}`);
+  }
+  if (typeof payload.total === 'number') {
+    console.log(`  Total: ${payload.total}`);
+  }
+  if (Array.isArray(payload.snapshots)) {
+    for (const item of payload.snapshots) {
+      console.log(`  - ${item.snapshot_id} | ${item.trigger} | ${item.created_at} | files=${item.file_count}`);
+    }
+  }
+  if (payload.created === false && payload.reason) {
+    console.log(`  Skipped: ${payload.reason}`);
+  }
+}
+
+async function runTimelineSaveCommand(options = {}, dependencies = {}) {
+  const store = createStore(dependencies);
+  const payload = await store.saveSnapshot({
+    trigger: normalizeText(options.trigger) || 'manual',
+    event: normalizeText(options.event) || 'manual.save',
+    summary: normalizeText(options.summary),
+    command: normalizeText(options.command)
+  });
+
+  const result = {
+    mode: 'timeline-save',
+    success: true,
+    snapshot: payload
+  };
+  printPayload(result, options.json, 'Timeline Save');
+  return result;
+}
+
+async function runTimelineAutoCommand(options = {}, dependencies = {}) {
+  const store = createStore(dependencies);
+  const payload = await store.maybeAutoSnapshot({
+    event: normalizeText(options.event) || 'auto.tick',
+    summary: normalizeText(options.summary),
+    intervalMinutes: options.interval
+  });
+
+  printPayload(payload, options.json, 'Timeline Auto');
+  return payload;
+}
+
+async function runTimelineListCommand(options = {}, dependencies = {}) {
+  const store = createStore(dependencies);
+  const payload = await store.listSnapshots({
+    limit: normalizePositiveInteger(options.limit, 20, 2000),
+    trigger: normalizeText(options.trigger)
+  });
+  printPayload(payload, options.json, 'Timeline List');
+  return payload;
+}
+
+async function runTimelineShowCommand(snapshotId, options = {}, dependencies = {}) {
+  const store = createStore(dependencies);
+  const payload = await store.getSnapshot(snapshotId);
+  printPayload(payload, options.json, 'Timeline Show');
+  return payload;
+}
+
+async function runTimelineRestoreCommand(snapshotId, options = {}, dependencies = {}) {
+  const store = createStore(dependencies);
+  const payload = await store.restoreSnapshot(snapshotId, {
+    prune: normalizeBoolean(options.prune, false),
+    preSave: options.preSave !== false
+  });
+  printPayload(payload, options.json, 'Timeline Restore');
+  return payload;
+}
+
+async function runTimelineConfigCommand(options = {}, dependencies = {}) {
+  const store = createStore(dependencies);
+
+  const patch = {};
+  if (typeof options.enabled !== 'undefined') {
+    patch.enabled = normalizeBoolean(options.enabled, true);
+  }
+  if (typeof options.interval !== 'undefined') {
+    patch.auto_interval_minutes = normalizePositiveInteger(options.interval, 30, 24 * 60);
+  }
+  if (typeof options.maxEntries !== 'undefined') {
+    patch.max_entries = normalizePositiveInteger(options.maxEntries, 120, 10000);
+  }
+
+  const hasPatch = Object.keys(patch).length > 0;
+  const payload = hasPatch
+    ? await store.updateConfig(patch)
+    : await store.getConfig();
+
+  const result = {
+    mode: 'timeline-config',
+    success: true,
+    updated: hasPatch,
+    config: payload
+  };
+  printPayload(result, options.json, 'Timeline Config');
+  return result;
+}
+
+async function runTimelinePushCommand(gitArgs = [], options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+
+  const checkpoint = await captureTimelineCheckpoint({
+    trigger: 'push',
+    event: 'git.push.preflight',
+    summary: normalizeText(options.summary) || 'pre-push timeline checkpoint',
+    command: `git push ${Array.isArray(gitArgs) ? gitArgs.join(' ') : ''}`.trim()
+  }, {
+    projectPath,
+    fileSystem: dependencies.fileSystem
+  });
+
+  const result = spawnSync('git', ['push', ...(Array.isArray(gitArgs) ? gitArgs : [])], {
+    cwd: projectPath,
+    stdio: 'inherit',
+    windowsHide: true
+  });
+
+  const statusCode = Number.isInteger(result.status) ? result.status : 1;
+  if (statusCode !== 0) {
+    const error = new Error(`git push failed with exit code ${statusCode}`);
+    error.exitCode = statusCode;
+    throw error;
+  }
+
+  const payload = {
+    mode: 'timeline-push',
+    success: true,
+    checkpoint,
+    command: `git push ${Array.isArray(gitArgs) ? gitArgs.join(' ') : ''}`.trim()
+  };
+
+  printPayload(payload, options.json, 'Timeline Push');
+  return payload;
+}
+
+async function safeRun(handler, options = {}, ...args) {
+  try {
+    await handler(...args, options);
+  } catch (error) {
+    if (options.json) {
+      console.log(JSON.stringify({ success: false, error: error.message }, null, 2));
+    } else {
+      console.error(chalk.red('Timeline command failed:'), error.message);
+    }
+    process.exitCode = error.exitCode || 1;
+  }
+}
+
+function registerTimelineCommands(program) {
+  const timeline = program
+    .command('timeline')
+    .description('Project local timeline snapshots (auto/key-event/manual/restore)');
+
+  timeline
+    .command('save')
+    .description('Create a manual timeline snapshot')
+    .option('--trigger <trigger>', 'Trigger label', 'manual')
+    .option('--event <event>', 'Event label', 'manual.save')
+    .option('--summary <text>', 'Summary for this checkpoint')
+    .option('--command <text>', 'Command context label')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => safeRun(runTimelineSaveCommand, options));
+
+  timeline
+    .command('auto')
+    .description('Run interval-based auto timeline snapshot check')
+    .option('--interval <minutes>', 'Override auto interval minutes')
+    .option('--event <event>', 'Event label', 'auto.tick')
+    .option('--summary <text>', 'Summary for auto checkpoint')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => safeRun(runTimelineAutoCommand, options));
+
+  timeline
+    .command('list')
+    .description('List timeline snapshots')
+    .option('--limit <n>', 'Maximum snapshots', '20')
+    .option('--trigger <trigger>', 'Filter by trigger')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => safeRun(runTimelineListCommand, options));
+
+  timeline
+    .command('show <snapshotId>')
+    .description('Show one timeline snapshot')
+    .option('--json', 'Output as JSON')
+    .action(async (snapshotId, options) => safeRun(runTimelineShowCommand, options, snapshotId));
+
+  timeline
+    .command('restore <snapshotId>')
+    .description('Restore workspace from a timeline snapshot')
+    .option('--prune', 'Delete files not present in snapshot (dangerous)')
+    .option('--no-pre-save', 'Do not create a pre-restore snapshot')
+    .option('--json', 'Output as JSON')
+    .action(async (snapshotId, options) => safeRun(runTimelineRestoreCommand, options, snapshotId));
+
+  timeline
+    .command('config')
+    .description('Show/update timeline config')
+    .option('--enabled <boolean>', 'Enable timeline (true/false)')
+    .option('--interval <minutes>', 'Auto snapshot interval in minutes')
+    .option('--max-entries <n>', 'Maximum retained snapshots')
+    .option('--json', 'Output as JSON')
+    .action(async (options) => safeRun(runTimelineConfigCommand, options));
+
+  timeline
+    .command('push [gitArgs...]')
+    .description('Create a pre-push timeline snapshot, then run git push')
+    .option('--summary <text>', 'Summary for pre-push checkpoint')
+    .option('--json', 'Output as JSON')
+    .action(async (gitArgs, options) => safeRun(runTimelinePushCommand, options, gitArgs));
+}
+
+module.exports = {
+  runTimelineSaveCommand,
+  runTimelineAutoCommand,
+  runTimelineListCommand,
+  runTimelineShowCommand,
+  runTimelineRestoreCommand,
+  runTimelineConfigCommand,
+  runTimelinePushCommand,
+  registerTimelineCommands
+};

package/lib/runtime/project-timeline.js

@@ -0,0 +1,598 @@
+const path = require('path');
+const { spawnSync } = require('child_process');
+const fs = require('fs-extra');
+const minimatchModule = require('minimatch');
+
+const minimatch = typeof minimatchModule === 'function'
+  ? minimatchModule
+  : (minimatchModule && typeof minimatchModule.minimatch === 'function'
+    ? minimatchModule.minimatch
+    : () => false);
+
+const TIMELINE_SCHEMA_VERSION = '1.0';
+const TIMELINE_CONFIG_RELATIVE_PATH = path.join('.sce', 'config', 'timeline.json');
+const TIMELINE_DIR = path.join('.sce', 'timeline');
+const TIMELINE_INDEX_FILE = 'index.json';
+const TIMELINE_SNAPSHOTS_DIR = 'snapshots';
+
+const DEFAULT_TIMELINE_CONFIG = Object.freeze({
+  enabled: true,
+  auto_interval_minutes: 30,
+  max_entries: 120,
+  exclude_paths: [
+    '.git/**',
+    'node_modules/**',
+    '.sce/timeline/**',
+    'coverage/**',
+    'dist/**',
+    'build/**',
+    '.next/**',
+    'tmp/**',
+    'temp/**'
+  ]
+});
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function normalizePosix(relativePath) {
+  return `${relativePath || ''}`.replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\//, '');
+}
+
+function normalizeBoolean(value, fallback = false) {
+  if (typeof value === 'boolean') {
+    return value;
+  }
+  const normalized = `${value || ''}`.trim().toLowerCase();
+  if (!normalized) {
+    return fallback;
+  }
+  if (['1', 'true', 'yes', 'y', 'on'].includes(normalized)) {
+    return true;
+  }
+  if (['0', 'false', 'no', 'n', 'off'].includes(normalized)) {
+    return false;
+  }
+  return fallback;
+}
+
+function normalizePositiveInteger(value, fallback, max = Number.MAX_SAFE_INTEGER) {
+  const parsed = Number.parseInt(`${value}`, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return fallback;
+  }
+  return Math.min(parsed, max);
+}
+
+function safeSnapshotId(value) {
+  return `${value || ''}`
+    .trim()
+    .replace(/[^a-zA-Z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 96);
+}
+
+function createSnapshotId(prefix = 'ts') {
+  const now = new Date();
+  const yyyy = now.getUTCFullYear();
+  const mm = `${now.getUTCMonth() + 1}`.padStart(2, '0');
+  const dd = `${now.getUTCDate()}`.padStart(2, '0');
+  const hh = `${now.getUTCHours()}`.padStart(2, '0');
+  const mi = `${now.getUTCMinutes()}`.padStart(2, '0');
+  const ss = `${now.getUTCSeconds()}`.padStart(2, '0');
+  const rand = Math.random().toString(36).slice(2, 8);
+  return `${prefix}-${yyyy}${mm}${dd}-${hh}${mi}${ss}-${rand}`;
+}
+
+class ProjectTimelineStore {
+  constructor(projectPath = process.cwd(), fileSystem = fs) {
+    this._projectPath = projectPath;
+    this._fileSystem = fileSystem;
+    this._timelineDir = path.join(projectPath, TIMELINE_DIR);
+    this._indexPath = path.join(this._timelineDir, TIMELINE_INDEX_FILE);
+    this._snapshotsDir = path.join(this._timelineDir, TIMELINE_SNAPSHOTS_DIR);
+    this._configPath = path.join(projectPath, TIMELINE_CONFIG_RELATIVE_PATH);
+  }
+
+  async getConfig() {
+    let filePayload = {};
+    if (await this._fileSystem.pathExists(this._configPath)) {
+      try {
+        filePayload = await this._fileSystem.readJson(this._configPath);
+      } catch (_error) {
+        filePayload = {};
+      }
+    }
+
+    const merged = {
+      ...DEFAULT_TIMELINE_CONFIG,
+      ...(filePayload && typeof filePayload === 'object' ? filePayload : {})
+    };
+
+    merged.enabled = normalizeBoolean(merged.enabled, DEFAULT_TIMELINE_CONFIG.enabled);
+    merged.auto_interval_minutes = normalizePositiveInteger(
+      merged.auto_interval_minutes,
+      DEFAULT_TIMELINE_CONFIG.auto_interval_minutes,
+      24 * 60
+    );
+    merged.max_entries = normalizePositiveInteger(
+      merged.max_entries,
+      DEFAULT_TIMELINE_CONFIG.max_entries,
+      10000
+    );
+
+    const rawExcludes = Array.isArray(merged.exclude_paths)
+      ? merged.exclude_paths
+      : DEFAULT_TIMELINE_CONFIG.exclude_paths;
+    merged.exclude_paths = Array.from(new Set(
+      rawExcludes
+        .map((item) => normalizePosix(item))
+        .filter(Boolean)
+    ));
+
+    return merged;
+  }
+
+  async updateConfig(patch = {}) {
+    const current = await this.getConfig();
+    const next = {
+      ...current,
+      ...(patch && typeof patch === 'object' ? patch : {})
+    };
+
+    next.enabled = normalizeBoolean(next.enabled, current.enabled);
+    next.auto_interval_minutes = normalizePositiveInteger(next.auto_interval_minutes, current.auto_interval_minutes, 24 * 60);
+    next.max_entries = normalizePositiveInteger(next.max_entries, current.max_entries, 10000);
+    next.exclude_paths = Array.from(new Set(
+      (Array.isArray(next.exclude_paths) ? next.exclude_paths : current.exclude_paths)
+        .map((item) => normalizePosix(item))
+        .filter(Boolean)
+    ));
+
+    await this._fileSystem.ensureDir(path.dirname(this._configPath));
+    await this._fileSystem.writeJson(this._configPath, next, { spaces: 2 });
+    return next;
+  }
+
+  async maybeAutoSnapshot(options = {}) {
+    const config = await this.getConfig();
+    if (!config.enabled) {
+      return {
+        mode: 'timeline-auto',
+        success: true,
+        created: false,
+        reason: 'disabled'
+      };
+    }
+
+    const index = await this._readIndex();
+    const latest = index.snapshots[0] || null;
+    const intervalMinutes = normalizePositiveInteger(options.intervalMinutes, config.auto_interval_minutes, 24 * 60);
+
+    if (latest && latest.created_at) {
+      const elapsedMs = Date.now() - Date.parse(latest.created_at);
+      if (Number.isFinite(elapsedMs) && elapsedMs < intervalMinutes * 60 * 1000) {
+        return {
+          mode: 'timeline-auto',
+          success: true,
+          created: false,
+          reason: 'interval-not-reached',
+          latest_snapshot_id: latest.snapshot_id,
+          minutes_remaining: Math.max(0, Math.ceil((intervalMinutes * 60 * 1000 - elapsedMs) / 60000))
+        };
+      }
+    }
+
+    const created = await this.saveSnapshot({
+      trigger: 'auto',
+      event: options.event || 'auto.tick',
+      summary: options.summary || 'auto timeline checkpoint'
+    });
+    return {
+      mode: 'timeline-auto',
+      success: true,
+      created: true,
+      snapshot: created
+    };
+  }
+
+  async saveSnapshot(options = {}) {
+    const config = await this.getConfig();
+    if (!config.enabled && options.force !== true) {
+      return {
+        mode: 'timeline-save',
+        success: true,
+        created: false,
+        reason: 'disabled'
+      };
+    }
+
+    await this._fileSystem.ensureDir(this._snapshotsDir);
+
+    const requestedId = safeSnapshotId(options.snapshotId);
+    const snapshotId = requestedId || createSnapshotId('tl');
+    const createdAt = nowIso();
+
+    const snapshotRoot = path.join(this._snapshotsDir, snapshotId);
+    const workspaceRoot = path.join(snapshotRoot, 'workspace');
+    await this._fileSystem.ensureDir(workspaceRoot);
+
+    const excludePatterns = this._buildExcludePatterns(config.exclude_paths);
+    const files = await this._collectWorkspaceFiles(excludePatterns);
+
+    let totalBytes = 0;
+    for (const relativePath of files) {
+      const sourcePath = path.join(this._projectPath, relativePath);
+      const targetPath = path.join(workspaceRoot, relativePath);
+      await this._fileSystem.ensureDir(path.dirname(targetPath));
+      await this._fileSystem.copyFile(sourcePath, targetPath);
+      const stat = await this._fileSystem.stat(targetPath);
+      totalBytes += Number(stat.size || 0);
+    }
+
+    const metadata = {
+      schema_version: TIMELINE_SCHEMA_VERSION,
+      snapshot_id: snapshotId,
+      created_at: createdAt,
+      trigger: `${options.trigger || 'manual'}`,
+      event: `${options.event || 'manual.save'}`,
+      summary: `${options.summary || ''}`.trim(),
+      session_id: `${options.sessionId || ''}`.trim() || null,
+      scene_id: `${options.sceneId || ''}`.trim() || null,
+      command: `${options.command || ''}`.trim() || null,
+      file_count: files.length,
+      total_bytes: totalBytes,
+      git: this._readGitStatus(),
+      files_manifest: 'files.json'
+    };
+
+    await this._fileSystem.writeJson(path.join(snapshotRoot, 'snapshot.json'), metadata, { spaces: 2 });
+    await this._fileSystem.writeJson(path.join(snapshotRoot, 'files.json'), {
+      snapshot_id: snapshotId,
+      file_count: files.length,
+      files
+    }, { spaces: 2 });
+
+    const index = await this._readIndex();
+    const entry = {
+      snapshot_id: snapshotId,
+      created_at: createdAt,
+      trigger: metadata.trigger,
+      event: metadata.event,
+      summary: metadata.summary,
+      scene_id: metadata.scene_id,
+      session_id: metadata.session_id,
+      command: metadata.command,
+      file_count: files.length,
+      total_bytes: totalBytes,
+      path: this._toRelativePosix(snapshotRoot),
+      git: metadata.git
+    };
+
+    index.snapshots = Array.isArray(index.snapshots) ? index.snapshots : [];
+    index.snapshots.unshift(entry);
+
+    const limit = normalizePositiveInteger(config.max_entries, DEFAULT_TIMELINE_CONFIG.max_entries, 10000);
+    if (index.snapshots.length > limit) {
+      const removed = index.snapshots.splice(limit);
+      for (const obsolete of removed) {
+        const obsoletePath = path.join(this._projectPath, normalizePosix(obsolete.path || ''));
+        try {
+          await this._fileSystem.remove(obsoletePath);
+        } catch (_error) {
+          // best effort cleanup
+        }
+      }
+    }
+
+    await this._writeIndex(index);
+
+    return {
+      ...entry,
+      snapshot_root: snapshotRoot,
+      workspace_root: workspaceRoot
+    };
+  }
+
+  async listSnapshots(options = {}) {
+    const index = await this._readIndex();
+    const trigger = `${options.trigger || ''}`.trim();
+    const limit = normalizePositiveInteger(options.limit, 20, 1000);
+
+    let snapshots = Array.isArray(index.snapshots) ? [...index.snapshots] : [];
+    if (trigger) {
+      snapshots = snapshots.filter((item) => `${item.trigger || ''}`.trim() === trigger);
+    }
+    snapshots = snapshots.slice(0, limit);
+
+    return {
+      mode: 'timeline-list',
+      success: true,
+      total: snapshots.length,
+      snapshots
+    };
+  }
+
+  async getSnapshot(snapshotId) {
+    const normalizedId = safeSnapshotId(snapshotId);
+    if (!normalizedId) {
+      throw new Error('snapshotId is required');
+    }
+
+    const index = await this._readIndex();
+    const entry = index.snapshots.find((item) => item.snapshot_id === normalizedId);
+    if (!entry) {
+      throw new Error(`Timeline snapshot not found: ${normalizedId}`);
+    }
+
+    const snapshotRoot = path.join(this._projectPath, normalizePosix(entry.path || ''));
+    const metadataPath = path.join(snapshotRoot, 'snapshot.json');
+    const filesPath = path.join(snapshotRoot, 'files.json');
+
+    let metadata = null;
+    let files = null;
+    try {
+      metadata = await this._fileSystem.readJson(metadataPath);
+    } catch (_error) {
+      metadata = null;
+    }
+    try {
+      files = await this._fileSystem.readJson(filesPath);
+    } catch (_error) {
+      files = null;
+    }
+
+    return {
+      mode: 'timeline-show',
+      success: true,
+      snapshot: entry,
+      metadata,
+      files
+    };
+  }
+
+  async restoreSnapshot(snapshotId, options = {}) {
+    const normalizedId = safeSnapshotId(snapshotId);
+    if (!normalizedId) {
+      throw new Error('snapshotId is required');
+    }
+
+    const config = await this.getConfig();
+    const index = await this._readIndex();
+    const entry = index.snapshots.find((item) => item.snapshot_id === normalizedId);
+    if (!entry) {
+      throw new Error(`Timeline snapshot not found: ${normalizedId}`);
+    }
+
+    const snapshotRoot = path.join(this._projectPath, normalizePosix(entry.path || ''));
+    const workspaceRoot = path.join(snapshotRoot, 'workspace');
+    if (!await this._fileSystem.pathExists(workspaceRoot)) {
+      throw new Error(`Timeline snapshot workspace missing: ${normalizedId}`);
+    }
+
+    if (options.preSave !== false) {
+      await this.saveSnapshot({
+        trigger: 'manual',
+        event: 'restore.pre-save',
+        summary: `pre-restore checkpoint before ${normalizedId}`,
+        force: true
+      });
+    }
+
+    const excludePatterns = this._buildExcludePatterns(config.exclude_paths);
+    const snapshotFiles = await this._collectFilesFromDirectory(workspaceRoot, excludePatterns, true);
+
+    for (const relativePath of snapshotFiles) {
+      const sourcePath = path.join(workspaceRoot, relativePath);
+      const targetPath = path.join(this._projectPath, relativePath);
+      await this._fileSystem.ensureDir(path.dirname(targetPath));
+      await this._fileSystem.copyFile(sourcePath, targetPath);
+    }
+
+    if (options.prune === true) {
+      const currentFiles = await this._collectWorkspaceFiles(excludePatterns);
+      const snapshotSet = new Set(snapshotFiles);
+      for (const relativePath of currentFiles) {
+        if (!snapshotSet.has(relativePath)) {
+          await this._fileSystem.remove(path.join(this._projectPath, relativePath));
+        }
+      }
+    }
+
+    const restored = await this.saveSnapshot({
+      trigger: 'restore',
+      event: 'restore.completed',
+      summary: `restored from ${normalizedId}`,
+      force: true
+    });
+
+    return {
+      mode: 'timeline-restore',
+      success: true,
+      restored_from: normalizedId,
+      restored_snapshot: restored,
+      pruned: options.prune === true
+    };
+  }
+
+  _buildExcludePatterns(configPatterns = []) {
+    const defaults = DEFAULT_TIMELINE_CONFIG.exclude_paths;
+    return Array.from(new Set([
+      ...defaults,
+      ...(Array.isArray(configPatterns) ? configPatterns : [])
+    ].map((item) => normalizePosix(item)).filter(Boolean)));
+  }
+
+  _isExcluded(relativePath, patterns = []) {
+    const normalized = normalizePosix(relativePath);
+    if (!normalized) {
+      return false;
+    }
+    for (const pattern of patterns) {
+      if (minimatch(normalized, pattern, { dot: true })) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  async _collectWorkspaceFiles(excludePatterns = []) {
+    return this._collectFilesFromDirectory(this._projectPath, excludePatterns, false);
+  }
+
+  async _collectFilesFromDirectory(rootPath, excludePatterns = [], relativeMode = false) {
+    const files = [];
+    const queue = [''];
+
+    while (queue.length > 0) {
+      const currentRelative = queue.shift();
+      const currentAbsolute = currentRelative
+        ? path.join(rootPath, currentRelative)
+        : rootPath;
+
+      let entries = [];
+      try {
+        entries = await this._fileSystem.readdir(currentAbsolute, { withFileTypes: true });
+      } catch (_error) {
+        continue;
+      }
+
+      for (const entry of entries) {
+        const childRelative = currentRelative
+          ? normalizePosix(path.join(currentRelative, entry.name))
+          : normalizePosix(entry.name);
+
+        if (this._isExcluded(childRelative, excludePatterns)) {
+          continue;
+        }
+
+        if (entry.isDirectory()) {
+          queue.push(childRelative);
+          continue;
+        }
+
+        if (!entry.isFile()) {
+          continue;
+        }
+
+        files.push(relativeMode ? childRelative : childRelative);
+      }
+    }
+
+    files.sort();
+    return files;
+  }
+
+  _toRelativePosix(absolutePath) {
+    return path.relative(this._projectPath, absolutePath).replace(/\\/g, '/');
+  }
+
+  _readGitStatus() {
+    const branch = this._spawnGit(['rev-parse', '--abbrev-ref', 'HEAD']);
+    const head = this._spawnGit(['rev-parse', 'HEAD']);
+    const porcelain = this._spawnGit(['status', '--porcelain']);
+    const dirtyFiles = porcelain.ok
+      ? porcelain.stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean)
+      : [];
+    return {
+      branch: branch.ok ? branch.stdout : null,
+      head: head.ok ? head.stdout : null,
+      dirty: dirtyFiles.length > 0,
+      dirty_count: dirtyFiles.length,
+      dirty_files: dirtyFiles.slice(0, 100)
+    };
+  }
+
+  _spawnGit(args = []) {
+    try {
+      const result = spawnSync('git', args, {
+        cwd: this._projectPath,
+        encoding: 'utf8',
+        windowsHide: true
+      });
+      if (result.status !== 0) {
+        return { ok: false, stdout: '', stderr: `${result.stderr || ''}`.trim() };
+      }
+      return { ok: true, stdout: `${result.stdout || ''}`.trim(), stderr: '' };
+    } catch (error) {
+      return { ok: false, stdout: '', stderr: error.message };
+    }
+  }
+
+  async _readIndex() {
+    if (!await this._fileSystem.pathExists(this._indexPath)) {
+      return {
+        schema_version: TIMELINE_SCHEMA_VERSION,
+        updated_at: nowIso(),
+        snapshots: []
+      };
+    }
+
+    try {
+      const payload = await this._fileSystem.readJson(this._indexPath);
+      return {
+        schema_version: payload && payload.schema_version ? payload.schema_version : TIMELINE_SCHEMA_VERSION,
+        updated_at: payload && payload.updated_at ? payload.updated_at : nowIso(),
+        snapshots: Array.isArray(payload && payload.snapshots) ? payload.snapshots : []
+      };
+    } catch (_error) {
+      return {
+        schema_version: TIMELINE_SCHEMA_VERSION,
+        updated_at: nowIso(),
+        snapshots: []
+      };
+    }
+  }
+
+  async _writeIndex(index = {}) {
+    const payload = {
+      schema_version: TIMELINE_SCHEMA_VERSION,
+      updated_at: nowIso(),
+      snapshots: Array.isArray(index.snapshots) ? index.snapshots : []
+    };
+
+    await this._fileSystem.ensureDir(this._timelineDir);
+    await this._fileSystem.writeJson(this._indexPath, payload, { spaces: 2 });
+    return payload;
+  }
+}
+
+async function captureTimelineCheckpoint(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const store = dependencies.timelineStore || new ProjectTimelineStore(projectPath, dependencies.fileSystem || fs);
+
+  try {
+    if (options.auto !== false) {
+      await store.maybeAutoSnapshot({
+        event: options.event || 'checkpoint.auto',
+        summary: options.autoSummary || options.summary || ''
+      });
+    }
+    return await store.saveSnapshot({
+      trigger: options.trigger || 'key-event',
+      event: options.event || 'checkpoint.event',
+      summary: options.summary || '',
+      command: options.command || '',
+      sessionId: options.sessionId,
+      sceneId: options.sceneId
+    });
+  } catch (error) {
+    return {
+      mode: 'timeline-checkpoint',
+      success: false,
+      error: error.message
+    };
+  }
+}
+
+module.exports = {
+  ProjectTimelineStore,
+  TIMELINE_SCHEMA_VERSION,
+  TIMELINE_CONFIG_RELATIVE_PATH,
+  TIMELINE_DIR,
+  TIMELINE_INDEX_FILE,
+  TIMELINE_SNAPSHOTS_DIR,
+  DEFAULT_TIMELINE_CONFIG,
+  captureTimelineCheckpoint
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scene-capability-engine",
-  "version": "3.3.25",
+  "version": "3.3.26",
   "description": "SCE (Scene Capability Engine) - A CLI tool and npm package for spec-driven development with AI coding assistants.",
   "main": "index.js",
   "bin": {