scene-capability-engine 3.3.24 → 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.
@@ -42,6 +47,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - when `--spec` is omitted, `plan` auto-selects the latest scene-matching chain (`scene_id`)
   - `sce studio generate` writes chain-aware metadata and `generate` stage report at `.sce/reports/studio/generate-<job-id>.json`
   - `sce studio verify` / `sce studio release` now include domain-chain metadata in reports and pass `spec_id` into auto errorbook failure capture
+- Added historical related-spec retrieval for faster new-problem analysis:
+  - 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

@@ -20,6 +20,8 @@ const { registerSpecBootstrapCommand } = require('../lib/commands/spec-bootstrap
 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 {
@@ -57,6 +59,7 @@ const program = new Command();
  * - `sce spec pipeline ...` -> `sce spec-pipeline ...`
  * - `sce spec gate ...` -> `sce spec-gate ...`
  * - `sce spec domain ...` -> `sce spec-domain ...`
+ * - `sce spec related ...` -> `sce spec-related ...`
  * - `sce spec create <name> ...` -> `sce create-spec <name> ...`
  * - `sce spec <name> ...` -> `sce create-spec <name> ...` (legacy)
  *
@@ -96,6 +99,11 @@ function normalizeSpecCommandArgs(argv) {
     return normalized;
   }
 
+  if (commandToken === 'related') {
+    normalized.splice(commandIndex, 2, 'spec-related');
+    return normalized;
+  }
+
   if (commandToken === 'create') {
     normalized.splice(commandIndex, 2, 'create-spec');
     return normalized;
@@ -342,6 +350,9 @@ registerSpecGateCommand(program);
 // Spec domain modeling command
 registerSpecDomainCommand(program);
 
+// Spec related lookup command
+registerSpecRelatedCommand(program);
+
 // 系统诊断命令
 program
   .command('doctor')
@@ -810,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
 
 ---
@@ -73,6 +73,10 @@ sce spec domain init --spec 01-00-feature-name --scene scene.customer-order-inve
 sce spec domain validate --spec 01-00-feature-name --fail-on-error --json
 sce spec domain refresh --spec 01-00-feature-name --scene scene.customer-order-inventory --json
 
+# Find related historical specs before starting a new analysis
+sce spec related --query "customer order inventory reconciliation drift" --scene scene.customer-order-inventory --json
+sce spec related --spec 01-00-feature-name --limit 8 --json
+
 # Multi-Spec mode defaults to orchestrate routing
 sce spec bootstrap --specs "spec-a,spec-b" --max-parallel 3
 sce spec pipeline run --specs "spec-a,spec-b" --max-parallel 3
@@ -92,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
@@ -491,6 +526,7 @@ Stage guardrails are enforced by default:
 - `plan` requires `--scene`; SCE binds one active primary session per scene
 - `plan --spec <id>` (recommended) ingests `.sce/specs/<spec>/custom/problem-domain-chain.json` into studio job context
 - when `--spec` is omitted, `plan` auto-resolves the latest matching spec chain by `scene_id` when available
+- `plan` auto-searches related historical specs by `scene + goal` and writes top candidates into job metadata (`source.related_specs`)
 - successful `release` auto-archives current scene session and auto-opens the next scene cycle session
 - `generate` requires `plan`
 - `generate` consumes the plan-stage domain-chain context and writes chain-aware metadata/report (`.sce/reports/studio/generate-<job-id>.json`)

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/spec-related.js

@@ -0,0 +1,70 @@
+const chalk = require('chalk');
+const { findRelatedSpecs } = require('../spec/related-specs');
+
+function normalizeText(value) {
+  if (typeof value !== 'string') {
+    return '';
+  }
+  return value.trim();
+}
+
+async function runSpecRelatedCommand(options = {}, dependencies = {}) {
+  const query = normalizeText(options.query);
+  const sceneId = normalizeText(options.scene);
+  const specId = normalizeText(options.spec);
+
+  if (!query && !sceneId && !specId) {
+    throw new Error('At least one selector is required: --query or --scene or --spec');
+  }
+
+  const payload = await findRelatedSpecs({
+    query,
+    sceneId,
+    sourceSpecId: specId,
+    limit: options.limit
+  }, dependencies);
+
+  if (options.json) {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log(chalk.blue('Related Specs'));
+    console.log(`  Query: ${payload.query || '(none)'}`);
+    console.log(`  Scene: ${payload.scene_id || '(none)'}`);
+    console.log(`  Source Spec: ${payload.source_spec_id || '(none)'}`);
+    console.log(`  Candidates: ${payload.total_candidates}`);
+    for (const item of payload.related_specs) {
+      console.log(`  - ${item.spec_id} | score=${item.score} | scene=${item.scene_id || 'n/a'}`);
+    }
+  }
+
+  return payload;
+}
+
+function registerSpecRelatedCommand(program) {
+  program
+    .command('spec-related')
+    .description('Find previously related Specs by query/scene context')
+    .option('--query <text>', 'Problem statement or search query')
+    .option('--scene <scene-id>', 'Scene id for scene-aligned lookup')
+    .option('--spec <spec-id>', 'Use existing spec as query seed')
+    .option('--limit <n>', 'Maximum related specs to return', '5')
+    .option('--json', 'Output machine-readable JSON')
+    .action(async (options) => {
+      try {
+        await runSpecRelatedCommand(options);
+      } catch (error) {
+        if (options.json) {
+          console.log(JSON.stringify({ success: false, error: error.message }, null, 2));
+        } else {
+          console.error(chalk.red('❌ spec-related failed:'), error.message);
+        }
+        process.exit(1);
+      }
+    });
+}
+
+module.exports = {
+  runSpecRelatedCommand,
+  registerSpecRelatedCommand
+};
+

package/lib/commands/studio.js

@@ -8,6 +8,8 @@ const {
   DOMAIN_CHAIN_RELATIVE_PATH,
   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'];
@@ -986,6 +988,25 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
     projectPath,
     fileSystem
   });
+  const relatedSpecLookup = await findRelatedSpecs({
+    query: normalizeString(options.goal),
+    sceneId,
+    limit: 8,
+    excludeSpecId: domainChainBinding.spec_id || specId || null
+  }, {
+    projectPath,
+    fileSystem
+  });
+  const relatedSpecItems = Array.isArray(relatedSpecLookup.related_specs)
+    ? relatedSpecLookup.related_specs.map((item) => ({
+      spec_id: item.spec_id,
+      scene_id: item.scene_id || null,
+      score: Number(item.score || 0),
+      reasons: Array.isArray(item.reasons) ? item.reasons : [],
+      matched_tokens: Array.isArray(item.matched_tokens) ? item.matched_tokens : [],
+      updated_at: item.updated_at || null
+    }))
+    : [];
 
   const paths = resolveStudioPaths(projectPath);
   await ensureStudioDirectories(paths, fileSystem);
@@ -1013,7 +1034,9 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
       domain_chain_spec_id: domainChainBinding.spec_id || null,
       domain_chain_path: domainChainBinding.chain_path || null,
       domain_chain_summary: domainChainBinding.summary || null,
-      domain_chain_reason: domainChainBinding.reason || null
+      domain_chain_reason: domainChainBinding.reason || null,
+      related_specs_total: Number(relatedSpecLookup.total_candidates || 0),
+      related_specs_top: relatedSpecItems
     }
   };
 
@@ -1040,11 +1063,18 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
         summary: domainChainBinding.summary || null,
         context: domainChainBinding.context || null,
         updated_at: domainChainBinding.updated_at || null
+      },
+      related_specs: {
+        query: relatedSpecLookup.query || '',
+        scene_id: relatedSpecLookup.scene_id || null,
+        total_candidates: Number(relatedSpecLookup.total_candidates || 0),
+        items: relatedSpecItems
       }
     },
     scene: {
       id: sceneId,
-      spec_id: domainChainBinding.spec_id || specId || null
+      spec_id: domainChainBinding.spec_id || specId || null,
+      related_spec_ids: relatedSpecItems.map((item) => item.spec_id)
     },
     session: {
       policy: 'mandatory.scene-primary',
@@ -1073,7 +1103,9 @@ async function runStudioPlanCommand(options = {}, dependencies = {}) {
     domain_chain_resolved: domainChainBinding.resolved === true,
     domain_chain_source: domainChainBinding.source || 'none',
     domain_chain_spec_id: domainChainBinding.spec_id || null,
-    domain_chain_path: domainChainBinding.chain_path || null
+    domain_chain_path: domainChainBinding.chain_path || null,
+    related_specs_total: Number(relatedSpecLookup.total_candidates || 0),
+    related_spec_ids: relatedSpecItems.map((item) => item.spec_id)
   }, fileSystem);
   await writeLatestJob(paths, jobId, fileSystem);
 
@@ -1605,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}`));
@@ -1629,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')
@@ -1639,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')
@@ -1649,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')
@@ -1657,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')
@@ -1669,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')
@@ -1684,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')
@@ -1694,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 = {